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PREFACE 


The  Apple  Ilt;s^"  Luirijuittfr  is  llie  ruosl  poweriiil  ineiiiWr  of  the  Applt®  II  fiimily 
of  inicmctunptiters-  Nal  surprisingly,  it  is  also  the  most  coinplex.  rt]id  llie  must 
difTituh  In  prngraiii. 

The  purpose  of  ihis  book  is  to  show  \ou  how  (o  develop  software  that  takes 
advantage  of  ihf  unique  features  nf  t}ie  i.s  without  tiirtiii^  >(MI  to  ^lifl  l}ir(iu)!;h  the 
thousands  ul'  pa^t^a  of  leL'htii^-al  iiilurniijlion  available  Iruiii  Apple  Cuiiipuler.  luf, 
The  major  new  features  1  will  eover  iiR'lude  the  enhanced  t>peratin{>  svfteiii 
(PruDOS®  161,  a  powc-rhil  ^nund  4yslH?in,  two  ■jupt-r  hi^li-resulutinn  eolor  Graiiliits 
display  modes,  atid  hundreds  of  standard  suliroutines  Lulled  fuiicliuti^,  a  pru^rym 
Ciin  use  to  perform  various  operations. 

The  CS  operating  sysleni  jirniips  related  soflWHre  funetiints  inli)  data  struftures 
called  Ivul  ■sei'i.  TVo  exainpleii  toul  sets  are  the  Meiuury  Manager  (».vhieh  toiitrols 
memory  usage)  and  the  Event  Miiniiger  (whith  deals  with  user  input  aetivily}.  The 
GS  also  has  several  toni  sets  yoti  cun  use  to  develop  progratns  thai  lake  advanlage 
of  die  desktop  efivimnnient  popularized  hy  the  M  jtintosh^"  L-tnnpnter,  tlie  iiKiiii 
ones  arc  QiuekDraw  il  (for  drawing  on  the  graphics  streenl,  the  Menu  Manager 
(fnr  implementing  pnll-dowii  menus],  the  Window  Manager  (for  handling  multiple 
windows  on  the  graphics  screen),  and  tlie  Dialofi;  Manuger  {loi  handling  user  selec- 
rionst, 

All  the  fommonly-ri'ied  tool  sets  are  anah  zed  in  this  hnok.  For  convenience,  tool 
scl  reference  fables  are  included  at  the  end  of  every  chapter  that  reviews  a  tool  sel. 
For  each  hmction,  these  tables  contain  the  function  number  and  the  list  ofparam- 
et^Ts  the  functioTi  cxp^-tts  io  receive  when  called. 

The  prngramniing  oiampk-s  in  this  book  were  written  in  iwiMB  assembly  lan- 
gnagf-  [There  is  a  good  reason  for  this:  highdevel  iangUEige  coinpilers  for  C.  Pascal, 
and  BASIC  were  not  available  when  this  lnwk  was  written.  ^  As  a  result,  yon  will 
find  this  book  mnre  valuable  if  you  have  ussembly  tanguage  experienL*,  Even  if  yun 
do  not,  however,  the  descriptions  of  what  the  tixil  set  fuiK  lion.^i  do  iind  how  they 
intcratl  with  one  snother  will  be  useful-  ('niiverting  assendih -langauge  function 
cails  to  high-level  langangc  eommand-s  should  mjt  Ix*  difficult. 

I  give  an  overview  of  65Slfi  assembly  language  programming  techin'ques  in 
chapter  2.  If  you  are  a  total  stranger  to  assembly  language  programming,  I  sn^gesl 
yon  first  read  a  hook  tolidly  devoted  lo  the  topic.  The  best  are  f}58lfi/f}5!i02  Assemblij 
iMiigua^t'  PitJgrawiiJiuig  by  Michael  Fischer  and  Frogrtintminfi,  Shi-  05S16  by  David 
Eyes  and  Ron  Lichty- 

As  yon  will  ijuic-kly  discover  while  reading  this  hook,  the  GS  supports  most  of  the 
hardware  and  software  features  of  the  Apple*  lie  and  lie  computers.  These  features 


V 


have  been  pxhaustivety  coverecf  in  three  of  my  t-arlier  Ixjuks,  Inside  the  Apple  lie. 
Inside  thu  Apple  lie,  and  Apple  ProDOS.  Advanced  t'eatttrei- for  Fiograimners.  The 
latter  hauk  describes  what  is  now  called  the  ProDOS®  B  iipemting  system. 


Il  would  not  have  been  possible  tn  writf  a  book  like  this  sn  soon  after  the 
introduction  of  the  cs  without  the  technica]  support  uf  Apple  Cumputer,  Inc.  My 
thanks  to  all  ihosf  at  Apple  who  put  up  with  my  many  telephomt;  aUk  and  elrctroiiic 
letters*  Those  who  were  particularly  helpfti!  were  Rob  Moore,  Jim  Mcrritt,  and 
Steve  Glass. 


Gary  B,  Little 

Vancouver,  British  Columbia,  Canada 
June  1987 
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CHAPTER  1 


Exploring 
the  Apple  IlGs 


On  SL-ptfmiiLT  15.  19HG.  Applt-  Compiiter,  Inc.  revealed  the  Apple  litis™  computer, 
the  krtit  new  iiindf]  in  the  Apple*  II  fainilv  siuve  the  Applf*'  Uv  (April,  19B4)  aail 
thf  Apple*  lit-  i|anuary,  1983)  roiiipiiters.  Tlie  CS  portKJii  cif  the  name  stunds  for 
Graphics  and  Smind,  tlu*  i\vii  t-Xfiliiig  kiiluri.'s  oi  [he  GS  that  distinguish  it  frnin  the 
Ik-,  lit,  and.  in  many  wa>s,  iruiii  iiiuit  other  nikrotointJUters  35  well. 

Biiildinf:;  tlit- 1;.'^  was  not  an  ensy  task  for  Apple's  cngiiiccrs  hpDiiuse  of  one  t-ritical 
design  Loiistraiiit:  the  CS,  ev^ii  with  its  iiincy  nrw  jioiind.  graphics,  and  proct-ssinK 
t^apaliditieb,  had  to  he  able  to  nni  Mul'twLire  originalK  dfvrlopt-d  fur  the  lit  and  lie. 
Nevertheless,  the*  project  was  siietessfully  completed.  The  result  is  a  computer  that 
runs  alriKLst  ull  sijfh^are  available  liir  the  lie  or  lie  hut  tlmt  h^^  ennugh  unique  new 
features  to  keep  pronranuner^  mid  users  s^itisfit'd  liir  yc-nr^  ta  L-cnne. 

lliis  eliapter  reviews  the  importniit  hardware  features  of  the  t;.s  while  hijihliphtinp; 
the  differences  l>fLviy?eii  the  cs  and  the  Ik'  and  Tk-  systems.  Also  prfivided  ii  ii 
cursi>r\  look  at  the  new  operating  system  software  Apple  provides;  with  ttie  CS.  Oiiee 
you  are  (]:mnliar  with  the  overall  makeup  nf  the  t;s,  you  will  quickly  recosuize  its 
potential  from  a  progriitnmer's  pnint  c)f  view.  Subsequent  chapters  examine  how  to 
develop  software  lor  the  GS  that  takes  full  advantage  ol  its  new  fealurei. 

MICROPKOCESSOR 

The  GS  uses  The  Western  Desit;n  C'cMiter  VV65CfiI6  inic  reprocess  or.  not  the  G5C02 
used  in  the  He  niid  He.  The  fiijfilfi,  as  it  is  mure  commonly  known,  is  a  versatile 
device  that  can  operate  in  an  S  hit  enudatiiiii  miKle  in  whieh  it  mimies  the  operation 
of  a  ahnost  e.xaetly,  or  in  a  more  powerful  Ift-bit  native  mode.  iSee  Appendix 

2  for  11  techniettl  desc-riptinn  of  the  fi5Mf>.) 

The  fiSMIG's  abihty  to  emulate  the  GSCOS  made  it  the  ohvious  choice  as  the 
microproce?;sor  for  the  cs.  \\'ithont  this  ability  to  emulate,  the  CS  would  not  he  able 
to  run  He  and  He  software  uiile.ss  a  .slow  soft\\are  inter|]reter  or  {heaven  forbid)  the 
65C()2  were  ii.sed. 
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Another  importaiil  latliiT  in  fhiiosing  the  fiSSiti  was  that  it  iil^o  has  enoiiuli 
horsejjower  ti)  hamdh-  ri.:jtiriju^  ntw  piiJK™iiniing  diort-s.  ••ulU  as  inaiiagiiL^  larRt 
anioiiiits  of  inr^mon."  and  pertorniiiiy  L-niiiph-.';  ci  ilnr  ,er;ipliicn  opemtirins.  In  its  nab've 
operaliiip;  jjukIp,  the  65816  supports  thf  foMowing  features:  16-hit  registers,  mare 
instriitliniis.  tiinn-  addres;iiii|^  niudes.  ;iiid  a  relocatable  direct  pagr  and  stack.  The 
also  has  a  24-bif  address  bus,  sl>  it  can  directly  address  a  16-nipgabyte  memory 

^>pace- 

The  I55S116  olenites  iit  either  1.0  MHz  {noTinal  mode)  or  2-S  MHz  [fast  mode)  on 
the  t:bi,  Tlw  default  made  is  the  fast  inude,  in  which  programs  run  abdut  two  and 
onc-hair  (iines  taster  than  they  do  at  numial  ^.perd.  Tlie  65C02  «in  the  Tfc  or  lit 
runs  at  only  1.0  MHz,  although  it  is  possihlc  to  purchase  accelerator  hoards  for  the 
lie  to  speed  it  up  hy  a  factor  of  three  or  more. 

MEMORY 

The  address  space  for  the  6.'5H]6  h  an  enormous  Ifi  meSiUiytes  and  is  directly 
addressahle  (that  is,  ever\'  byte  haj;  a  unique  address).  C'nntnLst  this  with  the  65C02, 
which  has  only  a  &4K  address  space;  additional  memury  cUiplicales  tliesc  addresses 
and  ean  ho  accesised  only  osiny  rplati\'ely  fflinple^  hanli-switching  tediniques. 

Chapter  -I  takes  a  detailed  limk  at  how  ihe  tis  makcK  mc  of  the  16M  address 
space.  In  brief,  a  standard  Ca  has  25(iK  nf  RAM,  expandable  to  SM,  und  12HK  of 
ROM.  espartdahlc  to  IM,  (I(  aisa  has  RAW  to  suppcjrt  the  sound  system  aiid  the 
f^ontrol  Paiieh  hut  this  ineijiury  is  not  pait  of  tlie  65^816  address  space.)  To  add 
estra  memory,  you  rrni.st  insert  a  memon,-  expansion  card  in  a  special  peripheral  slot 
on  thf  GS  mofherboHrd. 

0\  the  25fik.  of  RAM,  the  first  l2Hii  is  roughly  ctji-iivalent  In  main  and  iUJiiiliary 
memory  on  the  He  and  Ik.  Tile  other  12SK  is  needed  1o  supi^trt  the  operating 
system,  system  monitor,  dc\1ce  drivers,  and  special  video  displav  modes. 

Tine  ROM  sjiace  orj  tliF  c;s  contains  a  great  many  support  programs  and 

subroutines  u  prograiruner  can  use; 

•  The  same  Apple-snfl®  progranjiniiig  hm^uage  as  in  the  lie  and  lie 

•  A  Sy,^tem  Monitor  similar  to  the  ooe  on  the  IJf  aild  lit  but  wil)i  several  new 
commands 

■  A  Mini-Assembler  Hkc  the  imc  on  the  enhanced  lie  ami  lie.  bul  extended  to 
snpport  all  65^ilG  instructions  and  addressing  modes 

■  System  diagnostics 

•  Built-in  classic  desk  accessory  program.^;  Control  Patiel  (for  setting  the  system 
L>onfij;iitationl  and  .alternate  DuHphu  Mode  (Foir  allowing  He-  and  Ilc-stylc 
pro^jrams  lo  use  page  2  of  text) 

•  Drivers  for  built-in  inputVoutput  (I/O)  devices 
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■  A  driver  iinr  the  AppleTalk®  tiptwnrk 

■  Soft  switLhc-s  fur  t-oiifiguring  thv  system  and  performing  VO  operations  (these 
are  yc-tually  iiieiiuiry-mappM  I/O  kjt'atioiii ) 

•  Tool  sets:  Tool  Locator,  Mfinory  Siaiiage-r,  MiscellimKOUS  Tool  Sfft.  QuickDraw 
JI.  Sound  Manager.  Desk  ManaRer,  Float iii>;-Pt»]iiE  Nujuerics  (SANE™).  Appte 
DeskTop  Bus'"  Ttiol  Sel.  Sthediilcr,  Intetjtr  Math  Tool  Set,  Text  Tool  Set, 
Eveiit  Miiiiagcr,  and  ItAM  Diyk  TnnI  Set 

A  t(K>l  set  is  made  up  of  scvt-ral  subroutines  [or  Functions),  each  performing  the 
saiuE-  general  tj  pe  of  operation.  The  Memory  Manaf^er  tool  set,  for  example,  cuntains 
several  functions  for  doin^'  suth  chores  as  alloL'atini?  blocks  of  mfmnry,  releasing 
blocks,  calculating  free  space,  and  peribrniiTi||i;  other  metnory-rdated  operations. 
Most  of  this  book  deals  with  how  to  use  tool  set  functions  in  your  own  programs. 

I/O  INTERFACES 

From  an  I/O  point  of  view\  the  cs  combines  the  best  features  of  the  He  with  the 
best  features  of  thp  He.  Likf  the  Mr,  the  i:^  contains  seven  gcnerd-purpose  pe- 
ripheral evpansinn  slnts  numbered  from  1  tii  7.  As  a  result,  almtjsl:  any  peripheral 
board  originally  designed  for  the  lie  can  be  used  with  the  CS  as  welh  The  main 
exceptions  are  multifunetiun  cards,  such  a.s  the  Street  Bii«;inessGard  iiud  the  Pro- 
metheus Vcrs^card,  which  simuknr  the  effect  oi  havins  an  I/O  device  in  a  particular 
slot  even  though  the  card  plugs  into  a  diRerenl  slot.  (These  devices  are  said  to  u,se 
phantom  slots. ) 

The  cs  also  has  a  unique  eighth  slot  lor  memory  expansion  only.  ThronH;h  it  you 
can  add  up  to  S  megabytes  of  RAM  memory  as  well  as  additional  ROM  memory. 
Although  the  standard  Appb  c.s  Meniori'  Expansinn  t^ard  actually  holds  only  IM 
of  RAM,  other  ma[iufatturers  sell  cards  willi  greater  capacities.  (See  Appendiv  6  lur 
information  On  available  cs  memory  expansion  eard^i.^ 

In  a,dditian  to  expansion  kIcjIs,  the  OS  has  tht-  same  built-in  expansion  ports  as 
the  He,  plus  a  few  inort-.  Here  are  the  ones  that  eorrespund  to  standard  slot  numbers; 

■  Port  1:  serial  printer  port 

•  Port  S:  Aerial  modem  port 

•  Port  ,3:  video  port 

•  Port  4:  mouse  port  (part  of  the  Apple  DeskTop  Bu.s'") 
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Photo  I-l;     Thf  Back  Fand  of  llie  Applt-  lies,  ShnwiiiK  the  VO  Connectors 


•  Port  5:  dUk-drive  port  {SmiirtFnrt) 

•  Port  6;  5'/i-jnch  disk-drive  port 

'  Port  7:  AppleTalk  [actually  uses  atrial  port  I  or  2) 

A&  shown  in  phnto  1-1.  the  connectors  for  these  ports  arc  located  on  the  batk  panel 
of  the  CS. 

ThL=^  othtr  major  I/O  pnrts  are  two  game  eontrol  ports,  a  buOt-in  clofk/calt-ndar, 
and  a  sound  sjnthesizer, 

It  is  important  realize  thai  an  intrrrjal  pnrC  and  its  correspcmding  slot  a.]-c 
iniitnalh  exclusive.  In  other  word;.,  you  caji  use  oid>  unc  in  the  otht'r  II  is  nut 
po'isible  to  switch  between  an  internal  port  and  a  plug-in  ctird  without  turning  thc 
t:s  off  and  Cheii.  un  again, 

To  lell  the  Cb  whether  you  watit  tu  use  a  Jot  t:r  a  port,  von  miiit  use  a  built-in 
LonHguration  program  called  the  Couiml  Panel.  It  is  an  example  of  a  Cla.ssic  Desk 
Accessor'  {see  chapter  9J,  a  utility  program  you  can  switch  to  even  when  vou  are 
using  another  program. 
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To  brine  ^ip  ll'f  tl;iN.sif  dwRk  acct'sson,'  inriiu.  cnU-i  Ct)iitRjl-OptiiA|>plt^-i£st  fioiii 
ihf  k['yl>iiar(l.  This  prips  up  a  list  of  desk  dccfistirifs  y<iu  Liin  use.  lufpiiining  wilh 
ihf  Cuiitrol  I'Liiiei.  To  utUvatt'  thv  (^^nijtrnl  PaTu  l,  use-  thv  up-  mid  tlowu-amnv  keys 
lo  inf)\f  llif  iiivtTse  bar  ini:r  its  niiine,  und  iIh-ti  press  Hfliim.  Ydh  will  llifii  iee 
the  iniiiri  (.■otiiiniiiid  menu  for  llio  CfMitml  Paiit'l  Most  (nf  rht-sf  L'ommiinds  are  for 
«"tliiig  ^Inlxd  parameters  that  tunfiRUR"  thu-  Hy_stcin  tht-  v^ay  ytni  want,  Kiir  f  Xiiuiplf . 
then*  Lirt'  LOinmiuids  to  set  the  diiti'  and  tiiiu",  dclault  vidfu  l' I iiirat-teri Cities,  Liiid 
krybfiard  iiptinns. 

Thf  SIntS  Ciiijimatld  i;-  iiscci  tn  svt  the  dcsirt'd  slot/piirt  LimRf^uriltiOii,  Onte  \'OU 
scl^'ct  it,  you  will  set"  Ji  list  nt  slot  luinitnT.'.  and  an  IndiLalkHi  nt  whetlitfr  a  built-iii 
pnrt  or  "Your  Card"  (n  var^  in  a  skit)  is  tn  hp  attive.  The  deflmlt  set-up  selects 
internal  i>iirts  I  thrnuRh  6  and  ynnr  card  iit  Nlnt  If  ynu  wanted  to  use  a  parallel 
printer  card  in  ;^!ot  I,  yon  would  use  the  nyl't-'irrow  key  to  fhauge  the  entry  lor 
slut  J  ti)  '  Vf>ar  Card.'  The  next  time  you  ^turl  up  the  CS.  the  card  in  slot  1  vvill  be 
used  instrad  ol' .serial  port  1. 

Tlif  paraim'tcTs  sfi  np  l>y  tht-  t^ontrnl  Fanel  are  slfjred  in  a  niemory  area  asso- 
ciatpd  with  tht*  t:s  doek  chip  Inot  part  d'  the  6.5Slfi  adifres.s  Space!.  This  memory 
area  is  nnnvdiatilf  (bfciuisc  ii  is  powered  by  the  L'k!tk's  battery),  so  the  cs  remeui- 
Ikt-s  the  (^iintrol  Panel  sLttlngs  even  when  the  us  is  tunitd  utl. 

BCA  Mini  Headphone  Jaek 

By  plujiginj;  headphones  into  ihf  HCA  mini  headphone  jack,  you  can  divert  sound 
from  the  s  oii-boai  d  speaker  to  the  jack.  Altbouf;h  it  is  a  stereophonic  jack,  th*' 
cs  Miund  eirenitry  sends  the  saiiii-  ont]^ut  signal  to  both  channels,  so  yon  will  not 
hear  tnic  sterfopbtmic  south!  nnlejis  ynn  add  an  optional  sound  card. 

Seriul  Ports 

Tlie  cs  hhi  tw'ii  built-in  serial  interface  ports  driven  by  a  Zilog  fi53it  Scria]  Cnin- 
jnuiiiealitHis  Contruller  (SCC).  the  same  chip  used  on  (he  Macintosh cnniputer. 
By  ennvention.  the  first  port  (purt  11  should  he  used  wilh  a  serial  printer,  sni:h  as 
the  linaseW  riter*  [l.  and  the  second  [port  2!  should  be  used  with  a  mndcni,  such 
AS,  the  Hayes  Suiartuiudeni.  Yuu  eaiL  also  use  either  port  to  txjuueet  the  CS  to  an 
AppleTalk  network;  hi  this  case  the  serial  port  you  choose  l>eliave5  like  a  pnil  7 
device. 

The  853fl  i.s  nut  the  ^ame  as  the  Serial  chi|5  USed  00  the  Ik  lUid  the  ,\plilc  Super 
Jierial  Card.  This  means  that  pruprams  kir  the  lie  or  Super  Serial  Card  that  aterss 
serial  harilware  rt'nisters  directly  will  not  v\(>rk  on  the  i:s  witluHit  a  nev^'  device 
driver,  Most  pm};rams  that  arc  chip-speeific  are  coininuin  cat  ions  projirains.  Printing 
prusrams  do  nut  usually  cause  problems,  because  output  goes  through  the  firmware 
that  conlroU  the  serial  port;  at  this  level,  the  serial  ports  are  largely  compatible. 
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The  game  1/0  jjort  is  a  nmc-pin  DB-9  cnntieclor  used  tn  interface  game  coritmllers 
such  as  jnystiLlvs.  paddles,  am}  pusli  IniHuiis.  It  is  f(|iiiviilt>rit  to  a  similar  port  tm 
the  liiitk  ui  tile  III'  iiiu!  lie.  Wjtli  it  you  tan  iiit-iisiirf  the  sfttint!;s  ol  four  varialilitf- 
resislaiK't'  devit-es  (such  as  two  X-Y  joystk-ks)  and  three  singlp-bit  switch  iiiputa. 

The  inothirlnHird  iif  the  i'r»  also  has  n  rectansular  16-piii  iianse  c-nmieirltir  that  is 
idcnticii]  to  tin.-  one  uii  tlie  lie.  It  provides  all  tht  eleetriLal  siyiiajs  of  the  gatne  1/0 
port  as  well  as  lour  sinple-hit  cmtput  aimuucmtor  sigiials  for  driving  indicator  hglits 
or  simplio  rielays 

Disk-drivi?  Port 

The  disk-dri\'e  port  is  .similar  to  the  line  on  llie  haclt  of  the  He.  It  is  an  Apple 
Smart  Pent  interl'aee.  whieh  lueLins  that  you  tan  tornicet  to  it  any  device  adhfrinp  to 
tliL'  Sniartl'orl  luirdware  mid  M)JK\ure  speciliciilioTis,  This  includf^s  3'/^-iiJch  drives, 
such  as  tht'  UniDisk'"  3.5  and  the  Apple  3,5  Drive,  and  5'/i-iiich  drives,  such  as 
the  V]iiDisk  5.25  and  the  DnnDisk"*. 

Tn  add  disk  drives  to  the  cs,  all  you  Ikivl-  to  dn  is  daisy-chain  thein  lo  the 
SinartPnrl  in  the  eorreet  order.  {Sec  appendix  7  for  information  on  available  IIcs 
disk  drives. )  The  Apple  3,5  Drives  niii.st  lie  lonneeted  first  [two  ma.\inii]inl.  followed 
liy  any  nnmlier  of  UniUisk  3.5  drives,  and  then  Ibllowed  by  any  Syi-iuch  drives 
{fvvo  niasimum).  Because  of  jjower  supply  limitations,  vou  shtmld  nut  :idd  more  than 
two  L  niDi.sk  3.5  drives  to  the  chain. 

The  (;s  Irculs  tlie  S'/i-ineh  drive.s  at  the  end  of  a  SmartPort  dewier  chain  b,5  port 
6  devices,  even  llicnipli  the  disk-dri\e  prtrt  is  inlemally  mapped  to  port  5.  Tins 
means  that  you  can  boot  from  the  5'/i-in[  h  drive  with  an  Applesoft  Pll#fi  enminand, 
If  you  want  to  use  >0llr  5V^-i^eh  drive^f  wilh  a  disk  LWilroller  cLird  iu  slut  fi  instead, 
use  the  ('ontml  Patiel  Slots  coniniaiul  to  chiinge  the  slot  (i  entr\  to  ""^'our  Card." 

The  CcHitrol  Panel  also  lets  >'ou  ehoose  which  disk  device  yon  want  the  c;s  tn 
boot  bum  when  you  turn  it  on  t)r  when  you  enter  Conlrol-OpenApple-Heset.  The 
dehiult  is  "Scan."  which  tells  the  t.s  tn  Irmk  for  ii  drive'  from  slot  7  down  to  slot  1 
and  III  liiiot  from  ihc  first  one  it  find.s  with  a  bootable  disk.  You  can  al.so  spccifv  a 
specific  .^kit  number  to  hoot  kum.  lIo  this  if  you  want  lo  lioot  chrectly  frnni  the  first 
3'/3-inch  disk  in  [>nrt  5  in.stead  of  irom  a  5'/i-ineh  disk  in  porl  6.  for  e.\ample. 

I'siiis  the  tloiilrci!  Patiel  IL\M  Disk  command,  ynu  ciin  also  allocate  an  area  of 
meiiMiry  tor  use  as  a  RAM  disk  device.  RAM  di'ik  ineimir)  ciMilains  data  that  i.s 
Ibruiatted  in  the  .same  way  as  on  a  ii'al  (Imk.  D.itii  ii  read  ur  wrilleii  osin^  the  same 
tojiiinand.-;  as  tor  u  Standard  drive,  hnt  [/()  operations  are  much  faster  hecau.sc  there 
is  no  waitint;  for  slow-moving  meeliiinieal  parts.  The  rniiiii  drawback  of  a  HAM  disk 
is  thai  data  nn  the  RAM  disk  disappears  when  you  turn  ol3' the  power,  .so  vou  mii.sl 
transfer  il  to  a  re;il  disk  before  lurnin^  ofi  the  compiiter, 

[f  the  l\A\l  di.sk  has  been  properly  fonnaticil  with  all  the  ende  necessary  (br 
booting.  >'on  uia>  uant  tn  assign  it  as  ihe  bnot  device  instead  of  a  real  disk  drive.  If 
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yod  (lu  the  operating  system  will  reload  more  quickly  after  a  Control -Open  Apple- 
Resel  relMJiit, 

The  ca  hIsci  suppcjrts  any  ROM  disk  device  you  might  have  ou  a  ineniiiry  fxpan- 
sion  card.  A  ROM  disk,  like  s  BAM  disk,  is  fa.sl,  hut  its  contents  are  permanent.  In 
a  typiual  cnhv.  a  ROM  disk  uoiild  cuntain  ihe  c;s  operating  system  and  ain  utility 
or  application  pni^raini.  to  which  you  need  instant  access. 

Analog  RCB  Video  Port 

Yiin  can  (Niiinrct  an  aiming  RCB  monitor,  suth  as  llie  AppleCnlur  RGB  N^jnitor.  tn 
the  analog  RCB  video  port  to  view  the  4,096  Lolurs  ihe  C.S  sup\H>rt:^  in  its  snper 
hijili-rcitolution  f^raphic  display  niode.  You  cannot  connetl  digital  RCB  inf>niturs  to 
this  port. 

Compojiilc  Color  Video  Port 

Tht'  cs  slso  generates  ait  NTSC-conipatible  cumptisite  L^ilor  video  output  signal. 
TIh'  port  connfttor  is  an  RCA  phoiia  coiuiectur.  You  can  use  the  NTSC  signal  to 
drive  an  ordinary  monothroniit?  monitor  tjr  a  coniposi le  culur  monitor. 

Apple  DeskTop  Bus  Port 

The  Apple  DeskTop  Bus  (ADB)  is  a  unique  data  IransoiisKion  intfrfatc  dcsiEtied  to 
allow  \im  to  connect,  in  a  chain,  certain  tyiJcs  tif  input  devices  to  th<'  t;s.  The  two 
mo.st  L'Ointnr]ii  .'VPB  de\  icus  arc  the  ke'> hoard  and  the  mouse,  whitli  Ltjmc  with  the 
Gs.  The  ADB  protocol  is  general  cnuugh,  however,  to  work  with  other  pnmtiiiK 
devicL's.  such  as  trackbidU  mid  joysticks.  The  as  communiciiteis  with  any  device  on 
thf  ADB  hy  sending  it  comniai^ds  and  listening  for  rfSpiuisf  LcnnmuoiLiition  siiinal), 
can  be  directed  to  a  particular  device  to  avoid  interTerin^  with  other  devices  in  the 
chain. 

Connected  directly  to  ihr  ADB  is  ihe  keyboard.  (See  pliutu  1-2).  It  contains  SO 
keys,  including  a  14-key  numeric  keypad.  The  layout  of  keys  is  almost  the  same  a-s 
the  layouts  on  the  He  and  He  keyboiirffs.  bill  with  one  importaiil  difference:  the 
Option  key  ^formerly  called  the  Solid-Apple  keyl  is  now  on  the  lelt  side  of  the  hpaee 
bar,  just  to  the  leH  of  the  Open-Apple  kry. 

The  main  new  feature  ol  the  keylioard  is  its  prnKramniahihty.  B>  chaiifiinp  Control 
Panel  parameters,  yuu  can  adjust  the  antn-repcat  rale  of  ihc  keys  iUKl  the  time  delay 
before  repeating  Ijejjins.  You  can  even  make  tEie  space  har^  Delete  key,  and  arrow- 
keys  repeat  mare  ipiickly  than  cither  keys.  Another  nice  Feature  is  the  ability  ti> 
enable  keyboard  huHerinj?;  alltiM-inj;  you  to  t\pe  ahead  of  your  prognlill.  Finally,  yuu 
can  deterndne,  (i-um  a  propram.  whether  any  key  on  the  keyboard  is  down,  e\en 
modifier  keys  hke  Shift,  ControK  and  Cap,s  Lt^k. 

Tfie  cs  keyboard  has  two  ADB  connectors,  one  for  attaching  it  to  the  ADB  port 
and  one  for  conneclitlg  it  to  the  next  device  in  the  .\DB  chain, 
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fhoto  1-3:     The  Applt-  IU.h  K(-yht>arc] 


TliP  next  tlfviff  is  usually  the  cs  mnuse.  For  eoiiipatihilih'  roasotis.  the  Ca  treats 
tho  moitSf  a.s  the  pprt  4  de\Lee.  evt.n  thnugh  il  is  really  part  nCthc  ADB  thaiii.  The 
standard  c;s  nioiise  contains  only  une  Inilhin,  l>u[  the  sy.st<_'iii  software  suppurts  Iwu- 
buttun  niiLt. 

REAL  TIME  CLOCK/CALENDAR 

The  t;s  is  the  (inly  member  of  the  Apple  11  liiniily  witli  a  hiiilt-fn  real-lime  eloek/ 
calendar  ehip.  With  tlif  help  uf  a  small  liattery  on  tlit-  iiiotheihuartl,  this  cliip  keeps 
trat'k  of  tht  eiirrent  date  aiKl  time,  e\  en  aiter  you  have  turned  ofl'  the  GS. 

The  newest  \crihions  of  the  fruDOS*'  opcrattnp  s\;itein  autoniatieiilly  reio^izc 
the  r;s  clock  and  will  use  il  to  time-  and  datr-stanip  Hies  wlu-n  they  iire  saved  to 
disk,  Yon  eaii  aku  read  (hf  clock  from  a  pro^jrinii  iiainn  two  tnol  set  I'uiittions  in 
ROM.  To  Set  tlie  titiie,  use  the  Control  Panel, 

You  tan  aild  aeloek  tt>  a  lie.  hut  nmst  nf  tht-  clocks  hein^^  sold  use  up  an  expansiun 
slot.  The  GS  ekjck,  on  the  other  handf,  dnt-s  not  occupy  a  Jot  (or  a  porll,  s.u  you  e;in 
sav  e  il  slot  for  JiuNie  other  t\pe  iif  peripheral. 
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VIDEO  DISPLAY  MODES 


The  GS  supports  all  the  staiidcird  video  di^iplay  modes  of  the  lie  and  lie,  plus  one 
important  new  mode.  The  standard  display  modes  are  as  follows: 

80-coluinii  text  mode.  The  dlmensiuns  ui'  the  screen  are  80  eulumns  hy  2-4  rows. 

40'Cotumii  text  mode.  The  diiriensiun:^  of  the  screen  are  40  Ltjlumni  by  24  lows. 

Low-re  solution  graphics  mode.  Tlie  dimensions  of  the  screen  are  40  dots  hori- 
zontally by  48  dots  verlitalEy,  Eacli  dot  can  he  one  nf  sixteen  colors. 

Double-low-resolutioii  graphics  mode,  llie  dimensions  of  the  screen  are  BO  dots 
hmzontally  hy  48  dots  vertically.  Each  dot  can  be  one  of  sixteen  colors. 

High-rcsolutioii  graphics  mode.  The  dimensions  of  the  screen  ;ire  280  dnts 
horizontally  by  192  dots  vertically.  Each  dot  can  be  one  of  six  colors;  color 
choices  depend  on  the  column  in  which  the  dot  is  found. 

Double- high- resolution  graphics  mitde.  The  dimension.';  of  the  screen  arc  560 
dots  horizontally  by  192  dots  verttc^ly.  This  mode  supports  sixteen  diffeirnt 
colors. 

The  GS  adds  two  minor  embellishments  to  the  text  modes:  the  color  of  text  charac-tcrs 
a.nd  !hc  background  color  are  user- selectable,  Use  the  Control  Panel  to  set  them  in 
any  of  sixteen  colors,  You  can  also  use  the  Control  Panel  to  set  a  screen  border 
color. 

Tlie  new  c.s  video  display  mode  is  the  super  high-resokition  fjraphics  mode,  It 
is  the  mtKle  used  tn  display  the  outstuiiding  color  graphics  images  lor  which  the  GS 
has  become  famou.^.  The  super  high-resolotioH  screen  is  200  dais  in  height.  The 
horizontal  dut  resolutiim  is  sepamtelv  enntrtillable  fnr  each  of  the  200  lines,  and  can 
be  320  dots  or  64U  dots,  Mijst  proyrams  keep  all  the  lines  at  the  same  resolution  to 
simplify'  graphics  operations. 

The  colors  available  in  super  hi^;h-resnluti[jn  graphics  mode  depend  on  the  hor- 
izoiitiil  resolution.  In  the  640-by-20Q  mode,  each  dot  can  be  ont  of  four  colors 
selected  from  a  group  of  sixteen  assigned  to  the  line.  The  foursome  available  depend-s 
on  the  coliiinn  position;  without  using  tricky  propramming  techniques,  only  256 
colors  may  appear  on  the  screen  at  once,  in  the  320-by-2tlO  innde.  each  dot  can  he 
one  of  sixteen  colors;  256  colors  may  appear  on  the  screen  at  once. 

The  colors  vised  in  super  high- re  solution  graphics  mode  are  eompU^tely  prn- 
grammable  and  are  formed  by  mixing  one  shade  of  red  with  une  shade  of  j^reen  and 
One  shade  of  bhie.  Because  16  shades  are  available  for  each  of  these  primary  colors, 
a  total  of  4,096  c-olors  can  be  generated, 
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SOUND 


The  GS  has  the  mnst  lid^  Eiinred  suund  L-upahility  of  iiny  iiiit:'r<)t;omputrr.  Ttitrkcd  away 
in  a  comer  of  the  niotherhuard  i:i  n  puwtrful  device,  i:uLled  an  Ecsonit]"*  Difi;ital 
Oscdiator  Cllip  (DOC),  whith  is  a  professionai-qudjity  Sj-nthesizer  for  music:,  speceh. 
and  sound.  This  same  chip  controk  the  popular  Mira|4;e  Music  Syntheiiizer  used  by 
musicians  around  the  world. 

By  feeding  the  EiLsoniq  chip  the  right  software,  you  can  create  amazing  audio 
effects,  from  symphonic  sound  to  your  own  voice.  The  chip  c-ontains  32  Oi^eilktiirs 
fgr  stepping  through  audio  waveform  tables,  so  theoretitally  yuu  tan  play  batk  32 
notes  simultaneously.  In  the  GS  implementation,  oscillators  are  paired  off  to  create 
15  generators  or  voices  (the  16th  geiierator  is  resened  tor  inteniai  use);  this  is  still 
enough  to  create  superb  sound  quality. 

You  can  ptay  back  aionophonic  .sound  on  the  cs  through  a  two-incli  ou-hoard 
speaker  or  thrtni^h  thf  RCA  mini  headphone  jack  on  the  back  panel.  If  vou  plug  in 
headphones,  the  speaker  is  automatically  disabled.  To  get  stereo  sound,  you  can 
add  an  inexpensive  hardware  demoltiplexer,  such  as  the  SuperSonic  card  from 
MDLdeas,  Such  a  device  samplfs  the  audio  wavpform  output  and  the  chiimiel 
number  (from  1  to  W).  Stereo  sound  is  then  created  hy  diverting  the  odd-numhered 
channels  to  one  speaker  and  the-  other  channels  to  the  other  speaVer  Of  course,  it 
is  up  to  the  iound- gene  rati  on  software  tc;  direct  the  outgoing  signal  to  different 
channels, 

The  GS  has  a  64K  liAM  area  that  is  used  for  storage  of  waveforms,  Thi.s  RAM  is 
not  part  of  the  65816  address  space,  hut  can  he  read  From  or  written  tu  through  s 
hardware  interface  called  the  Sound  Oneral  Lt)>;ic  Unit  [(^LU). 

The  Ensoniq  is  also  able  to  sample  incoming  analog  waveforms  und  store  them, 
in  digital  form,  in  its  64K  RAM  area.  Tliia  is  done  bv  attaching  the  incoming  sound 
aoiirLe,  such  as  a  microphone,  to  an  analog  input  wjuneetur  and  then  triggering 
analog-tij-digital  conversions  by  sending  commands  to  the  Ensonic;  chip. 

OPERATINC.  SYSTEM  SOFTWARE 

Over  the  past  ten  years  or  so,  Apple  has  developed  and  released  four  major  disk 
operating  systems  (or  tlie  Apple  II  family,  all  of  which  work  on  the  CS: 

•  DOS  (1978) 

-  UCSD  Pascal  (1979) 

•  ProPOS  B  (1983) 

•  ProDOS  16  il9S6) 
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Other  ciperatinK  sy.'iteiris  ^re  availalilc  from  thiVd-paity  dfvdopcrs,  but  only  CP/M 
sefiJis  to  efiicrate  miiL'li  iiilcrtst.  CP/M  tint'?!  nut  work  with  a  plain  GS;  you  will 
need  to  irisliilJ  u         ftjiirtjccisor  tard  Hml. 

DOS  3.3,  tiie  kteiit  (tind  final)  versiun  (if  Applt-'s  first  [^pcr^tin^  system,  is  no 
longer  actively  pr(;i)l[Ult;d  by  Apjlle.  Ntvf  rtliL-le^s,  it  timlii^u^-.s  Et>  fn=  popular  lurciiiise 
there  is  a  large  botly  »ii  iullvviirL-  wIulIi  vmrks  wilh  it.  DOS  3.3  dues  nnt  take 
adv'antaffe  of  ain-  special  features  of  the  cs,  and  it  dues  nut  work  [without  niodifi- 
eatitjn)  willi  -JViZ-iiuh  disk  dri\es  ur  liurd  drivt's.  it  wns  desipned  to  work  unly  with 
5'/i-iii[.-h  drives  and  llicir  ii-ssotiiUed  1-itlK  liuppy  disks, 

The  UCSD  Pascal  operating  system  is  primarily  lur  thuse  who  wish  to  program 
in  P;iscal.  At  one  time,  Paseal  seemed  tu  be  the  taiigULiKe  of  dioiee  for  edueiiturs 
beeau'if'  nfiiclipnt:;  are  able  to  learn  Hit  fiindiUiR-iittils  uf  ii  structured  prugrajuining 
lan^iaj!*"  quickly  by  writing  a  few  programs  in  Pastal.  Unlbrtunately,  UCSD  Paaca] 
lia.s  never  received  tlw  wide.'^prpad  support  whicli  DOS  3.3  or  ProDOS  has,  It  is 
eertainly  rare  to  find  a  professiniia.lK  piiblis^lied  progniin  for  the  Apple  II  written  in 
Paseal. 

Apple  relt'a.s£'(l  PrnDOS  fi  [it  was  orisinally  allied  just  "FroDOS  'J  tu  solve  the 
problem  tjf  usint!  high-caipaeitv  disks  iho  Apple  U  fiimily,  Orisintilly,  tliis  nieiint 
hard  disks  like  thp  Apple  ProFile'",  hut  the  cate^fory  now  includes  the  80tiK  HVi- 
inch  disku  used  by  the  Apple  3.5  Drive  and  the  ViiiDisk  3.,5,  ProDOS  8  works 
nicely  with  disk  vuhinies  up  to  32  megabytes  and  with  files  up  to  16  megabytes,  in 
addition,  it  uses  a  hierarehieal  direetory  structure  tn  make  it  easier  to  manage  the 
hundreds  of  file^  which  can  be  stored  on  high-capacitv  disks. 

ProDOS  16  is  the  only  Apple  II  nperaiinji  system  that  works  only  on  the  CS. 
Althniigli  it  uses  the  sAme  disk  file  jitora|L;e  format  as  ProDOS  8.  you  must  use 
difTerent  proEramrninf;  ttvhni[|ues  tn  cdntrol  it.  This  inrans  ProDOS  8  applicatioms 
uitl  nut  work  under  ProDOS  16,  and  (  ice-versa;  however,  you  can  store  tiles  created 
hy  either  uperaling  sy;>lein  on  the  same  disk, 

Apple  developed  ProDOS  16  Ibr  the  because  ProDOS  H  wtirks  only  with 
pnigratns  that  run  in  the  first  54K  of  memory  This  is  an  unreasonable  restriction 
in  a  system,  bke  the  GS,  tliat  has  a  Ifr-meguhyte  address  space.  With  ProDOS  16, 
ynu  can  issue  disk  roinmand^i  from  anywhere  in  memory-. 

ProDOS  16  is  described  in  greater  detail  in.  chapter  10.  For  an  in-dcpth  analysis 
ul  ProDOS  H.  reler  lo  the  l>ook  Apjile  ProDOS:  Aikuncfd  Features  for  Pntgrammers 
[Little,  19S5!-  Other  useful  books  are  listeil  lji  appendix  S, 

DEVELOPMENT  SOFTWARE 

The  nf^eial  development  software  for  the  t;,s  is  the  Apple  Programmer's  Workshop 
(APW).  ft  runs  under  ProDOS  16  and  is  distributed  on  HOOK  disks,  so  you  will  need 
ai  least  one  3V?-inch  disk  drive  to  use  it, 

AP'W  is  made  up  of  several  integrated  modules  acctsied  through  a  cooimon 
cummand  shell; 
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•  A  text  editor  for  freatinp  program  source  code 

•  A  hnVoT  For  toiiihiiiiiin  objfft  vndt;  inofliilcs  tTt-ated  hy  APW-c-ompalihle 
assemblers  and  furnpilt:ra 

•  A  65fjl6  asiemblicr  for  c-ompiling  assembly  lani^ua^e  progrJms 

•  A  65S16  debugger  ft>r  trat^king  dt>wn  errors  in  programs 

An  AFW-<;(nnpatil)lr  C  eominler  iN  also  aviuLiblc  from  Appk\  Similar  eoinpilers  for 
Pascal  and  liASiC  are  iviiilablc  fruni  tliird  parties  or  art-  in  LlfV'L--loi.Mnt.*nt.  (See 
ilppendi^  8.1 

Tbf  APW  shell  snpiwrts  many  commands  that  will  help  ynu  periiirm  cuminon 
sofH'ure  de\'ebpmrnt  tasks,  siicli  ils  imn  iiis  fiU'-.  fium  disk  tn  difik.  rL'iiaming  filers, 
deleting  files,  and  dispkyiiig  the  names  of  on-line  vuhinies. 

CREDITS 

So  whu  was  respon'iible  for  dcsiKninp  ihR  GS,  anyway^  The  answer  is  as  Llose  as 
your  keyboard,  Bemme  tlie  disk  from  your  start-up  driv*-  and  turn  tin  [or  reboot) 
the  GS..  A  "Chctk  startup  drvit-e!"  error  mossaffe  w  ill  appear  on  the  scTL-<_-n  along 
with  an  fipplp  icon  thai  slides  hack  and  fnrth.  Now  for  thr  setrel  eommand:  while 
hi)]ditig  down  the  Open-Appl(?  and  Option  keys,  t>pf  Control-N,  This  tells  the  t;s 
to  reveal  the  names  of  all  the  key  people  who  worked  on  the  GS  projeeL  Vou  read 
it  here  first. 
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CHAPTER  2 


Programming 
the  65816 
Microprocessor 


The  65816  miorDprncessor  that  controls  the  GS  can  oprratc  in  t-itlicr  enmliitiori  mode 
or  native  imKle.  In  eniulatiDii  mode,  th*'  Ii.i81fi  iimliTstands  tlit  *aine  iiistructsotis 
(ind  Sinnn  ntw  ones.  t(«)l  as  ihe  fi.'jCOS  iiitcTc>pn)i-'fs.st)i  in  tliL-  Apple  Ik-  and  the 
enhanced  Applf  lie.  Because  the  r,.s  hardwure  tan  emulate  the  ehariK'tcri'^tics  of 
the  He  and  Ik  aliiiosl  exactly,  this  mrtins  must  lie  and  lie  software  will  wnik  nn 
the  CS  without  inodiljcatinn. 

A'ote;  For  fonvenience,  consider  future  references  to  the  lie  as  references  tu  the 
lie  as  well. 

In  native  niodr.  Ihf  6^i8Ifi  supjjiirls  many  new  and  imixirtunt  features  that  m^ke 
it  snbstanlially  more  powerful  than  i\  f)5C02: 

■  A  directly  addrcssahle  Ifi-ine^abyte  address  space 

■  16-bit  atf  iimulator  and  index  registers 
•  IS-bit  memory  operations 

■  A  relocatable  stack  and  direct  pajge 

■  Many  extra  instruetions  and  addressing  modes 

By  exphiitinj;  th*^se  features,  developers  can  erratr  puwc-rliil  praRrams  niudi  mure 
easily  than  they  eould  on  a  lie  witli  a  65C02.  Refer  tt>  the  nianidiioturer's  (iSSlG 
data  sheet  in  appenthx  2  fur  a  delailpd  deseripticni  ni  ihe  mieropnicessor. 

The  65816  in  the  CS  is  able  to  operate  at  either  of  twu  speeds:  tlie  normal  1.0 
MHj"  rate  oi  the  lie  or  the  faster  rate  of  l.H  MHz,  (OverliL-'ad  ibr  RAW  refreshinE 
actually  reduces  the  average  fast  rate  from  2.S  MI]^  lo  2.5  M]  Inr  RAM  operatiims; 
ROM  operations  take  place  at  full  speed.)  iTie  faster  speed  is  the  default,  and  mnut 
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programs  will  run  properly  at  tlmt  spcrd.  Siimf'  Ilf  upplk-atioiii,  Imwever,  nrrtahlv 
ihosR  that  rely  ovi  preuisc  timing  kicips  (giunr-s  Mnd  .siriiiilaturi,  lor  i-xainplc),  may 
work  only  al  normal  spt-pd.  Yini  can  Llumse  the  curreiit  nperatin^  speed  with  the 
Coiitrnl  Panel  S\'st(fin  Spcpil  L^iinnuiiiil. 

Tliis  tliaptOT  inveitietiU-s  huw  thf-  fi5Slfi  optTutes,  Tliii  includes  an  examination 
nf  iti  iiilf  niiil  ri-gister^.  il^  instru(:ti<iTi  set  and  aildressinfi  nnK]es.  and  twp  important 
data  areas  called  tb.'  ^V^ck  and  diretl  page  Melhnds  *;f  ^Teatin^;  GSSlfi  prosrams 
iisinK  the-  ^PW  assembler  are  also  eOver<'d.  Throu^hcmt  the  thapter,  the  einpliiisis 
h  on  itatnres  unique  t<i  the  65Hlfi  running;  in  native  mode,  but  references  lo  65<:02 
eniuImicHl  mude  features  are  made  where  necessary. 


THE  65816  MEMORY  SPACE 

The  65816  has  a  ZA-hii  adilress  bus,  meaning  it  can  actess  an  enonnons  16-metfabyte 
(2^''  bytt-s)  n^rmnrv  space,  internally,  it  deals  with  tliis  mcnuin-  A'i  a  series  oi  MH 
banks.  niinil>erTd  rnnii  $flO  tn  SFF-  A  standard  cs  has  RAM  in  banks  SOU,  $01.  SEO. 
and  $E1  and  ROM  in  banks  HVE  and  JIFF,  Chapter  4  discusses  exactly  liow  the  cs 
makes  use  of  itM  meinor>'  spate. 

The  first  liunk.  bank  SOO,  has  special  qualified-  Jt  contains  two  interesting  data 
areas  ealled  tW  tHrert  ptifie  and  the  .Krtf^;-  In  niittvp  mode,  you  ran  place  these 
areas  anywbcn?  in  bank  &00.  In  t-mulalion  iniide.  ihc  stack  must  be  in  paye  SOI; 
the  direct  piigi'  can  be  any  page  in  bank  $00.  but  is  invariably  pafif  (zero  page). 
[A  pace  is  a  gnmp  of  256  consecutive  bytes  besiniiinji  at  an  address  whose  last  two 
dibits  are  S(H>.] 


Direct  Pafte 

The  25<i-byte  direct  pa^e  is  important  hccan^e  lhase  65S16  instructions  that  irake 
use  of  it  are  sliurter  and  faster  than  similar  inslruetinns  using  other  parts  of  memory  . 
Tlta!  is  because  the  jJuiEratll  needs  tn  provide  only  one  byte  of  address  informatinQ 
lu  the  65.S16  (the  offset  into  the  direct  paKe);  the  other  (wo  bytes  needed  to  lorm  a 
coniplcte  24-bit  address  are  taken  frnm  aji  internal  rrpster. 

More  iniportaiitly,  the  (y5bl6  lias  powerbd  iiidireel  indexed  uddressins  iiifjdes 
that  retjuire  you  to  place  a  pointer  to  a  data  .-itnjcture  in  direct  pnge.  Tn  access  a 
field  in  the  data  structure,  all  you  have  to  do  is  specify  the  direct  page  location  and 
the  offset  to  the  field.  Unlike  some  micniprotessors  [notably  the  OHtXX}),  the 
does  not  allow  yim  tu  uccc'-s  a  data  structure  indirectly  by  putting  its  address  in  a 
microprocessor  register;  this  makes  it  necessary  to  have  a  data  area  such  as  a  direct 
page. 

Wlien  you  are  developinJ^  programs  in  emnlation  mode,  it  is  cnmmofi  to  refer  to 
direct  page  as  zero  pagv.  because  it  should  be  kwated  at  page  !500  in  bank  $00.  as 
it  is  when  using  the  63t^(]2. 
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Thif'  sCat'l:  is  an  iircH  of  meinon-  that  is  implidtiy  used  hy  t-Ertain  65816  instruclions 
to  atiirt'  data.  This  area  is  "inverted"  in  the  sense  that  it  ^rows  down  in  inL'mur\-  as 
you  add  data  to  it  (a  "push"  operatinnj  and  shrinlcs  up  in  mcTnur^'  as  vim  remiive 
ddtj  frijin  it  {a  "piiH'  ojicratinn]. 

Thf  iiL'tivr  position  in  thf  stack  Is  ji^ivt-n  by  the  vdiit'  in  a  Ifi-Jiit  itatk  pointLT 
[SP)  rtfjiistcT.  cit'scrilic'd  bf|nw  [t  is  initially  set  to  the  last  hyle  (hiphes^t-atldresied 
byte)  in  tlic  kitack  ar''a 

It  in  iniportijnt  m  undt'rst<ind  the  inpchaiiifs  of  push  and  pull  operatiLins,  hefjiuse 
they  arc  used  'jiiitr  often.  When  ymi  push  a  byte  value  on  the  stack,  the  byte  is 
plHCfd  at  the  a,ddri-.ss  tliat  is  in  the  stack  puinler  and  ihe  slack  jiointer  is  decremented 
by  unt.  Whfu  a  liyti-  is  piillrd  fniui  tUn  stack,  tlie  sttick  pointer  is  iriLTeineiitt-d  and 
the  vidue  IS  Inadcd  frnin  the  new  address  it  rantaiiis.  TJie  imixjrtant  point  to  realizt; 
is  th;ll  the  Statk  jnHnter  always  pnjn(:s  hn  the  byte  just  below  the  last  item  pushed 
tin  the  stack. 

In  native  modr,  the  stack  cnuld  occupy  the  whole  of  hank  allbnuf^h  jiiosl 
pr(Ji;rani!i  iK'ver  nifd  mnrc  tbun  n  pa^t'  nr  tu'u.  In  eniulatitin  mode,  the  stack  is 
always  256  bytes  Um^  ajid  oLxupics  pa^e  401  of  bank  %tH), 
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Hcgistcrs  are  areas  i[iside  a  iinLTOprtx-essor  thai  the  niR'riiprucessor  uses  ttJ  Fitnrc 
values  and  manipulate  daUi.  They  are  n<il  memory  liK-dtlons  in  the  micrnpriK'cs.'inr's 
address  sprite.  In  lienenil,  the  mure  registers  a  niiL'niprcn;C-SSor  has,  thf  niQrc 
powerful  llie  iriiLruproeessur  is^  that  is  because  opcraCmns  involvinBi  registers  sre 
much  faster  than  similar  operations  invulvins  m^emiiri'  k>t"atinns. 

The  registers  u,>ied  liy  the  t>5Wltj  are  <i]iown  in  fif;nrc  2-J.  There  arc  nine  of  them: 

•  Accumiikitnr 

■  X  index  refjister 

■  Y  index  retjister 

•  Hata  hank  register 

■  PTC'>prajii  bank  reiiister 

•  Direct  page  register 

»  Pfoci'ssor  status  resi^ter 

■  Stack  pointer 

•  FrcjUrani  ojunter 
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Figure  2-1.     The  65816  Pi-Kistcr  Sets  in  Ennilalion  Mode  and  Native  Mode 
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PfMessor  Status  Register 

The  processor  status  resi^ter  (P)  ^oiM^\ns  a  proup  t^i'  st.tus  t\-^fis  and  mode  se\eci 
bits  that  reflect  the  operational  st^te  t>f  the  65816  ^.ee  figi-re  S-2).  Mo.l  msh  uct.ons 
eause  one  or  more  status  fla^s  tn  ehan«e  according;  to  the  operations  they  p*-rform; 
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Fipure  3-2.     The  Status  Flags  in  the  65S16  Proc-essor  Status  HetjKtLT 
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statiis-checkinfi  inHtructions  can  then  be  used  to  change  tjie  flow  of  a  projjriUTi  based 
on  the  result. 

Th<?  slruLture  of  the  .status  register  de[jeiid!i  on  whether  the  [Jnx:ess(ir  is  in 
emulation  mode  or  native  mude,  as  FigTire  1-2  indicates.  The  flai;s  in  llic  emulation 
mode  status  register  art  the  carry  Ha;;,  the  zeri)  fian.  the  IH(^  disabk'  fla^,  the 
dcciinal  mude  (Ian.  tin."  bre^ik  Haw,  the  uverfluw  Hiii;.  the  negative  flaii,  Lind  the 
emulation  Bag.  In  the  n^ilive  mude  sliilus  rei^isler.  the  bre^k  Hiiii,  is  i^jt  present,  the 
spare?  status  bil  is  used,  and  twu  resi-'iter-seleft  HnjJ^  are  available:  the  ]nenii>rj'/ 
aC'CUtnulalor  select  Haf;  and  the  index  refiister  s*?leL'l  fla^;.  The  flags  in  the  emulation 
mode  statuii  register  and  the  native  mode  status  rei^ister  are  diS'Cusseci  below. 


CBrry  Flag.  The  carry  flag  is  most  often  used  wlieu  performing:  addition  [ADC] 
or  subtraction  [SBC)  operations.  As  is  shown  later  in  this  Lhapter.  this  Hap  must  be 
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cleared  (with  CLC)  before  adding  two  numbers  and  must  he  set  [with  SEC)  before 
subtracting  two  nunfibt  is. 

The  carry  flag  is  also  used  hi  check  the  result  of  a  LOinpiurison  operation  (CMP. 
CPX,  CPY).  If  the  number  in  the  spet-ified  register  is  less  than  the  number  it  is 
beiiit;  mmjmred  to.  the  carr\'  flaj;  h  deiired^  ullierw'ise  it  is  set.  The  BCC  and  BCS 
braiR-h-Lin-coiiditinn  iiisiructimis  lvui  tlien  he  used  lo  switdi  coiitro!  tn  another  part 
ol  the  program  depending  on  the  result. 

TIm'  cuny  flag,  ^Un  participates  in  the  shift  iind  rotate  instructions:  ASL,  LSR, 
ROL,  aiid  PiOR.  These  instrtietiuns  are  described  later  in  this  chapter. 

Zero  Flag.  The  zero  flag  iiidieates  whether  the  re.%ult  of  the  last  ai-jthmetie  oper- 
ation or  rt  gislrr  loadinj;  operation  Wiis  zero.  If  it  was,  the  Tcrn  Bag  is  set  tu  1; 
utherwi^c,  it  IS  cleared  tu  0. 

IRQ  Dimhie  Flag.  The  IRQ  disable  flap  c-ontrol'i  hem-  the  65S16  reacts  to  hardware 
interrupt  rei^ueit  {IHQ)  signals.  (Inlerrupts  are  di-sciis^sed  later  in  this  Lhapler.!  If 
the  flafi  is  set  tu  1,  lltQ  interrupts  are  ignored;  Dthcrwlsf  the  65iil6  pn'xresses  them, 

Dectmaf  Mode  flag.  Tliis  flag  controls  the  t\pes  nf  numbers  the  6.5816  uses  to 
perlbrni  additiuu  (ADCl  and  subtraction  (SBCJ  operations.  When  the  decinial  mode 
Hac  in  oB.  standard  hinLiry  iirithnietic  rules  are  used.  This  is  the  motle  in  which  most 
programs  operate  tiiid  it  is  thr  drfanlt  mode  when  the  OS  is  turned  on. 

when  decimal  mode  is  oii.  the  ft'^^ilfi  ii.ssumes  all  nucnlsers  are  stored  in  binary- 
coded  decimal  tbrmat  and  generates  arithmetic  results  that  are  iu  this  format  as 
well,  In  this  format,  each  liyte  contains  exactly  two  digits  from  0  to  9:  the  most- 
siguificaul  digit  occupies  the  high-order  four  bits  of  the  byte. 

Brjeak  Ffag.  Tlip  Im^ak  Rag  indicates  whether  the  source  of  a  65S16  interrupt  in 
emulation  mode  is  a  BRK  ini^truetion  [the  Bag  is  ,set)  or  a  hardware  interrajDt  request 
ithe  flag  is  clear).  Unlike  native  mode.  BRIC  and  interrupt  rcqueit^  vector  to  the 
same  subroutine;  the  .subroutine  can  inspect  the  break  Rag  to  determine  the  cause 
of  the  interrupt. 

Overfiow  Ffeg-  The  overflow  flag  usuaffy  indicates  whether  the  re?iult  of  an  arith- 
metic operation  invaKing  twoVLXfmplement  (sicned)  numbers  is  within  prescribed 
limits  The  6.>iHlfi  uses  the  two's-cumplemenl  t'orni  for  signed  arithinehc  operations 
to  simpIifV'  internal  calculations.  The  limits  are  -liS  to  +  i£7  for  8-bit  numbers  and 
-3276S  to  +32767  for  16-bit  nundjers, 

The  most-significant  hit  nf  ts  two' s-eomp lenient  number  is  the  si};n  hit;  it  is  0  for 
positive  numbers  and  I  for  negative  numbers.  For  positive  numbers,  the  remaining 
bits  represent  the  magnitude  of  the  oniiiber  in  .standard  binary  furm. 
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ThingtS  airt'  nnt  quite  so  simple-  for  negative  iiumliers.  To  determine  the  two's- 
coniplen-ent  form,  take  Hit'  iibsulute  viiliii?  nf  thf  number,  complement  it,  then  add 
1  to  the  result.  Here  is  how  tu  form  -22,  for  esiUiiple: 

OO01  01  1  0      (  +  22  in  hmiiry) 
'  1 1  1  1  0  1  0  0  1     {  +  '22  Ltimple minted) 
i-^*  1     (add  1] 


1  1 1  0    0  1  0     f-22  m  two's-w>inplf  mt  nt  forni) 

Notice  I  hat  the  high-urdcr  bit  is  set^  identifying  this  as  a  negative  number. 

Neg^v  Flag,.  This  Aug  reUetts  the  vnhie  of  the  liigh-ordKr  bit  of  the  last  value 
transferred  directly  to  the  A,  X,  or  Y  reie;istcr  or  pLit  tliere  as  a  result  of  ii  calculation. 
The  hiph-urder  bit  is  hit  7  for  an  S-bit  rrgi^ter  or  bit  15  for  a  Ifi-liit  register. 

The  negative  Baj!,  derives  its  name  frdm  the  fact  that  the  hif^h-nrdcr  bit  of  a  two's- 
Lumplemenl  number  reflects  its  si^n:  if  the  hit  Is  1.  the  number  is  negative. 

Emuialion  Flag.  The  emiihtion  flag  hides  behind  the  carr>'  Hap  in  the  status 
register.  Vnu  ivill  use  it  tu  set  the  operating  mode  nf  Hw;  65816,  When  it  set  to 
1,  the  65816  operates  in  65C02  eniulatioii  mode;  when  it  is  0,  the  65816  operates 
iQ  native  mt>de. 

Enterin)^  native  mode  piiv<?s  the  vvay  to  poweirfii]  16-bit  register  and  memory 
iiperatjt>ns,  as  is  discussed  below, 

The  Only  way  to  affect  the  emulation  hit  is  to  set  or  clear  the  carrv  flag  (with 
SEC  Or  CLC}  iind  then  execute  Uit;  XCE  [cxthange  carry  with  ejnulatioii)  instruction. 

RegfafifT  Select  Flags.  There  are  two  repister  seleet  fla^s  in  the  native  mode  status 
register:  the  memory/awumulator  select  fluR  and  the  jndes  register  select  flaj;. 

The  index  register  select  bit  is  called  i  and  the  memorv/accuinulator  select  bit  is 
called  m.  When  x=L  the  6581fi's  X  und  Y  registers  arc  both  S  bits  in  size,  when 
r=0.  these  index  registers  are  16  hits.  Siinilarly.  when  hi^I  the  A  register  is  8  hits 
in  siSM-  and  all  memory  operations  (such  as  DEC.  INC.  ASL,  and  others)  involve 
one  byb:  only.  When  ot-O.  the  A  re^ster  is  16  bits  in  size  and  memory  operations 
act  o:i  two  consecutive  bytes  (a  word). 

\Aheii  die  m  and  x  bits  are  both  0,  the  65816  is  said  to  be  in  fidi  native  mode. 
This  is  the  miKle  you  will  usually  want  to  ii.se  when  you  develop  a  GS-speeifie 
application. 

The  fiofilfi  haji  two  special  instruetions  you  can  use  to  set  or  clear  the  m  and  r 
bits:  HEP  and  SEP.  To  dear  bits,  use  the  REP  instruction: 

BEP  #S001 1 OOOO  ;clear  m  and  x  bits 
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Not^■  As  is  discussed  later  in  this  chapter,  the  #  synibnl  means  the  number  is  a 
c-on.t;int.  not  an  address;  %  identities  tlie  nnmli^^r  as    binar>^  aumbrr.  - 

REP  clears  to  0  those  hits  in  the  status  re^istpr  lhat  cnrresptind  to  1  bits  m  the 
operand.  (The  operand  is  ttie  number  following  REP  )  Tlius,  ym.  would  use  BEF  to 
ic-Hvatt:  16-hit  regi^iter/meniorv  and  Indesinp  operations. 

Cimverselv  SEP  sets  to  1  those  bits  in  the  status  register  that  et^rrespoud  to  1 
bits  in  its  operand.  Use  SEP  to  revert  t^  8-hit  register>nieinor>'  and  indexing 
operations. 


Accumulator  • '  ■ 

The  accumulator  (A)  is  .n  8-hii  or  a  l6-bU  register.  depeiidi-^R  on  the  stat^:  of  die 
m  flas  in  the  native  mode  status  register.  (A^^tually,  even  in  8-bit  mode  you  can 
access  the  "other-  8  bits  of  the  accumulator  with  the  XBA  exchange  instmctioo.)  In 
emulation  mode,  Uic  actumulator  i'i  always  B  bits  in  size 

The  aecumulator  is  the  only  register  that  works  ^.ith  the  65816  s  addition  (ADC) 
and  subtraction  (SBC)  instnietions.  tn  fact,  th^t  is  howit  gets  its  name;  it  aec-umulatcs 
the  results  of  aritKineti.  operations.  It  ,s  also  the  only  register  which  participates  m 
iHSical  operations  [ORA.  AND,  XOR). 

Most  itistructLons  refer  to  the  acci-mulator  hy  the  symbol  A.  no  matter  what  its 
size.  Some  call  it  C  to  emphasize  that  they  act  on  the  entire  16  bits  even  if  the  m 
flae  is  1  The  two  halves  of  the  16-bit  registers  are  also  referred  to  as  A  ilow  B  bits) 
and  B  (kigh  H  bitsj.  This  is  for  the  benefit  of  the  XBA  instruction,  which  swaps  the 
two  halves  nf  the  16-bit  accumulator. 

Using  a  16-bit  accumulator  is  convenient  because  it  can  handle  numb<^rs  up  to 
65  535  (instead  of  just  255),  thus  simplifying  many  types  of  arithmetic  instructions. 

A  le-bit  accumulator  is  somewhat  le.s  c-onvenieat  for  dealmg  with  character 
strinRS  however,  because  vou  usually  want  to  load  only  ..ne  eb^racter  nito  the 
acenmulator  at  on.-e  In  these-  situations,  you  yn^y  want  to  temporarily  revert^o  ™ 
8-hit  register  using  the  SEP  #%tK)lt)0(>00  instruction-  _ 

IndeK  Registers 

The  index  registers  are  called  X  and  Y,  They  are  commonly  used  to  hold  offsets  into 
a  data  structure  from  a  fixed  reference  location;  hence  the  name  mdex. 

Like  the  aceortiulatar.  the  index  registers  are  S  bits  in  iize  in  emulation  made. 
In  native  mode,  they  can  he  either  8  bits  or  16  hits  in  size:  if  the  x  flag  is  0,  t^eV 
are  16-hit  registers;  if  it  is  1,  they  are  8-hit  registers. 

Note  that  the  X  flag  always  affects  holli  index  registers,  it  is  not  possible  to  hwe 
X  and  Y  registers  that  are  different  sizes,  " 

\ 
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Stack  Pointer 


Tlic  Ki-hit  stack  poiiiler  resisteT  (SP)  (nYinis.  to  -m  address  in  hank  StKt  itut  is  on*- 
hytc  liplow  ihe  iHltiress  of  the-  last  vaUib-  pu^ht-J  on  tlie  statk  It  ^lulnmatiLalU 
decreases  after  push  instructions,  sueh  as  PIIA  and  PH\.  and  incTeases  after  pup 
instnicrioTis.  sndi  lis  Pi  A  siicl  Pl.X, 

In  cmidatiun  mode,  thf  liigh-order  hyk' of  the  atauk  pointer  is  always  $01,  so  the 
stack  is  ciinfincd  to  256  bytes. 

Direct  Page  Register 

The  l6-hil  direct  pa^e  register  [Dl  contains  the  address  of  the  start  of  the  direct 
page  ill  haiik  ^Wl  It  can  contaii]  uiiy  vaJiie.  hut  direct  paj;c  operations  art  iastcj  if 
dirf-cl  pi^i^c  begins  on  a  page  boundary.  In  einulLitton  mode,  tlie  direct  page  register 
>;hoidd  be  s,et  to  SOO, 

Data  Bank  Rei^ister 

Tlie  8-bit  data  bank  register  (h)  indicates  the  default  memnry  liank  for  nn;iinir>' 
access  operblions,  When  \i>ii  speeily  a  16-!)it  address  in  an  instruction,  the  fi5H16 
taleulates  the  hill  24-bit  address  hy  LtHicateTiatin^  the  diita  hank  rt'gistcr-  In  emu- 
lation mode,  the  data  bank  ref^ister  should  be  set  to 

FrogrHJn  Bank  Register 

Tlie  program  liank  re^i.ster  {K)  is  an  H-hit  register  thai  indicates  in  which  memory 
bank  the  torrent  projijrain  is  (jperatiiij;.  It  eomliint's  with  the  16-bit  progranj  counter 
register  to  mark  the  exact  pusitiim  in  memory-  iif  the  in.st ruction  currently  being 
exetuted, 

Tliere  is  no  explicit  instrtietion  for  changing  the  proj;ram  hank  register,  it  im- 
plicitly changes  when  the  program  transfers  control  io  another  hank  with  u  JSL  or 
JHP  instruction, 

In  emulation  [iiode^  the  progran:!  bank  register  should  be  set  to  £UU. 
Program  Counter 

The  16-bil  prt*gram  ctmnter  (PC)  holds  the  offset  from  the  start  of  the  current 
proflraill  buok  of  the  insliuctiun  currently  hein^  executed.  The  65SKi  automatically 
ijiLTeiiienLs  llie  PC  is  it  [irocesses  insiructiims,  usually  by  adding  \\w  size  of  the 
instructioai  Just  executed.  Wlleu  a  flow  of  eontri)]  instriiction  such  a.s  J\1P  itr  BRA 
is  encountered  [see  below),  Imvvever.  the  operand  addres-;  is  put  into  the  PC.  causing 
c.fccittion  to  continue  at  the  target  address, 


The  65H16  Registers  21 


Note  that  when  the  PC  chanjtes  from  SFFFF  tt;  SOOOD  at  a  memury  bant  hoimil- 
ar>'.  \h^•  prGgrum  bank  rfgister  h  not  incrfnitnied.  Thi-^  nn'ans  coiitml  passes 
to  ihf  bL'^innin^  uf  thf  cuireTil  bank,  mft  tu  the  begmnin^;  of  the  next  bank,  As  a 
result,  a,  65S16  program  ii  nut  perinittt-d  tn  cross  a  bank  houmlary.  although  it  can 
call  a  pruRrain  or  suhroutiin;  in  atiothtr  hiink.  On  the  cs.  the  ProDOS  Ifi  program 
loader  always  loads  a  prugrain  into  a  sin^I^e  hank, 

THE  65S16  INSTRUCTIONS 

lilt-  65816  supports  91  ditfureiit  instructions  [Scf  appendix  2  for  detailed  deicrip- 
tioiis  of  each.]  This  inekides  cveiy  65C02  instmetiim  as  well  as  27  instructions 
unique  to  the  654116,  Each  instmctiun  may  us<'  one  or  more  addressing  modes  Co 
IfKiate  data  it  uses;  the  number  of  in  struct  ion/addres  si  np  mode  combinations  is  256. 
Vou  will  find  a  description  of  addres.5inK  modes  in  the  next  section. 

A  one-byte  binary  opcode  tells  the  63f5l6  what  the  iiistmctiun  Is  and  what 
addressing  mtwle  it  is  iisinjj;.  You  du  not  hiivg  to  memorize  these  (ipeodes.  hecacse 
yon  will  use  an  assembler  tn  tonvert  nmeiiionic  instructions  and  addressing  modes 
in  a  source  code  file  to  binary  oiiject-code  form. 

Following  the  opcode  (here  may  be  up  to  three  operand  bytes  describing  a 
number  or  an  aiidress  to  he  u^trd  by  the  instruction,  Mnltihytc  operands  are  always 
stored  with  the  low-order  byte  first.  Again,  the  assembler  takes  care  ol  arran^in^ 
these  bytes  properly  ftir  you. 

The  next  seLlioii  of  this  chapter  examines  the  65816  instructions,  discussing  what 
the>  do,  and  how  ihey  .should  be  used-  Beter  tn  table  R2-1  (in  the  referente  section 
at  the  end  of  the  chapter]  fur  an  alphabetical  list  ol"  instructions.  This  table  also 
contains  the  pennitled  addressing  modes  and  opcodes  for  each  instruetion  type  as 
well  ai,  the  number  of  cycles  the  6.5Mtfi  uses  to  compbte  each  instruction. 

iThe  time  for  one  cycle  is  (he  reciprocal  of  the  clnck  speed-  The  clock  speed  is 
either  2.8  MHz  or  1.0  MHz.  dependniK  on  the  setting  (ff  the  Control  Panel  System 
Speed  option  For  prii^riims  oijcratinf;  in  R.AM  in  tl^st  mode,  the  average  clock 
speed  is  actualb  about  2.5  MHz  because  oloverheiid  introdoLcd  by  RAM  reireshitig 
requirements.^ 

A'cjlf.  histnictinns  marked  with  an  asterisk  in  the  fi>llinving  sections  are  not 
supported  by  the  (i5Cl>2  microprocessor, 

Load/Store  Instructions 

LDA  Load  the  accumulator  (liyte  ur  word) 

LDX  l-oad  the  \  rejiisler  (byte  or  word) 

LDY  Ixtad  the  Y  reffister  Ihytp  or  word} 

STA  St<]re  the  aceumvilator  |hyte  or  word! 

STX  Stui-e  the  X  register  [byte  or  word) 

STY  Store  the  Y  regi-ster  (byte  or  word) 

ST2  Store  xero  lo  mtinory  {byte  or  word) 
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The  fiiit  three  instructions,  LDA.  LDX.  and  LDY.  let  you  load  ^i-  or  16-bit  vsiliies 
into  tKe  aLtiiniiilatnr  and  index  registers,  Tlie  data  size  depends  on  the  settings  of 
the  m  and  t  hits  in  tiic'  fioHlfi  status  register,  Tlie  vakie  can  be  a  speL-i£ic  nujnber 
or  a  numlier  stored  at  a  given  mcmor>'  location. 

The  STA,  STX,  and  STY  instrin  tinns  1ft  ynij  transfer  the  contents  oi'  a  register 
to  a  particular  iiienioi'\'  litciition.  S1"Z  .stores  a  zero  at  a  memory  location. 

Wlieii  loading  word-sized  valueji  from  a  ^ivcn  address,  keep  in  oiiiid  that  the 
Inw-nrder  S  bits  of  the  register  are  fillt-d  witli  the  niiinhfr  stnred  at  Addrt'ss  and 
the  high-order  H  bits  nce  fillfd  with  tlie  number  stured  at  Addre-ss+1  [tht?  next 
higher  address).  Similarly,  when  storing  words,  the  low-order  S  hits  of  the  register 
are  stored  first. 

Push  Instructions 

"PEfl  Push  effective  3.hsolut<'  address  (word) 

■P£  ]  Push  effective  jndircLt  address  [word) 

■PES  Pus.h  effective  I'rlaljvt'  address  (word] 

PHA  Push  the  aceumulator  (byte  or  word) 

»PHB  Push  the  datii  bank  rej^ister  (hytp) 

*PHD  Pu.sli  the  direet  ]5aj;e  rcf;inter  (word) 

■PHK  Puih  the  pruffram  bank  reyihter  (byte) 

PHP  Push  the  atiitus  register  [byte) 

PHX  Push  the  X  rej^ister  [hyte  or  wurd) 

PHY  Push  the  Y  rejpster  (byte  or  word) 

Use  the  push  instruetious  to  transfer  data  to  the  top  of  the  stack  and  dpcrcitient  the 
-stack  pointer  by  the  data  size.  The  data  size  is  either  byte  or  word,  depending  on 
the  instruction  and  the  settings  ofthe  m  and  x  status  bits.  Word  uperands  are  pushed 
hi[j;h-ordf'r  bvtc  first. 

PHA.  PHfi.  PHD.  PHK,  PHP,  PHX,  and  PHY  all  push  the  eiintents  uf  a  Register 
On  the  stack.  PKA,  PEl,  and  PER  posh  two-byte  addresses,  as  follows^ 

PEA  pushes  an  absolute  IG-bit  address;  most  programmers  really  use  it  tn  push 
numeric  ^n.-vtants,  however,  bec^ause  it  does  not  involve  loading  the  Ltmslant 
into  a  register  first. 

PEl  pushes  the  address  stored  in  two  TOUsecutive  direct  page  locations. 

PER  pushes  tht-  address,  which  is  a  specified  nijmf>er  of  bytes  from  the  position 
of  the  instruction.  Tliis  instruction  is  useful  if  you  are  developing  relocatable 
code  (code  that  runs  at  any  load  address). 

The  operand  for  a  PEA,  PEl.  cir  PER  iiistruetioii  gives  the  65816  the  address  it 
needs  to  work  with. 
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Pull  Instructioivs 

PL  Pi  Pull  the  aLCumulatar  Owtp  word) 

•  PLB  Pull  diUii  liank  re&isL«?r  (byte) 

*PLD  Full  direct  pd.^e  register  (word) 

PLP  PuU  .status  rcfiister  (byte) 

PL  X  P'lll  X  registtfr  {hyte  or  word) 

PLY  Pull  V  register  (byte  ur  wurd) 


These  in.t..ct.u..r.n*rd.turrun,  the  tupofthest.ck...are^^^^^^^^ 

Ihe  .l^-V  pointer  by  one  thyte  operation)  or        (^vord  operating),  operand. 

are  popped  low-order  byte  first. 


Inler-register  Transfer  Instructions 

TAX  Transfer  A  to  X 

TAY  Transfer  A  t(i  Y 

TSX  Triuisfcr  S  to  X 

TXS  Tninsfcr  X  to  S 

TXA  Transfer  X  to  A 

TYA  Transfer  Y  to  A 

«TCD  Transfer  C  to  D 

•TDC  Transfer  D  to  C 

#TCS  Transfer  C  lo  S 

•  TSC  Transfer  S  to  C 

•  TXY  Transfer  X  to  Y 

•  TYX  Transrer  Y  tti  X 

Nvie:  D  =  data  bank  register;  C  -  16-bit  accumulator 


The  i«ter-regi.ter  tr..sfer  instructions  let  you  mov.  dat.  from  '^^'f^'^^^f'l^ 
r.Jn.  for  wanting  to  do  thi.  ar.  to  initialize  the  .ta.k  pomter  (T^S.  ICS) 

^"  Be^S^^  :St^^s^  -truetions  u,  .b.  l.t  .  yo.  tr.n.terrm. 
be„;lter.  of  H,ffLnt  .i.e.  Fo.  ^  and  ITA,  i  .^1  -d^-"-/ 

-i-  .f  tb.  in™^^  not 

affected.  For  TXS.  the  high-order  stack  register  hylc  is  .eroed  li  i-l 
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Eicchange  Instructions 

*XBA       Exchange  B  and  A 

*XCE       Exchange  carry  and  emulation  bits 

The  t'.'.'o  exchange  instructions  involve  manipulating  bits  inside  registers.  XBA  swaps 
thr  upper  half  of  the  Ifi-hit  a«uniula(or  iB)  with  the  lower  half.  \CE  swaps  (he 
carr>^  bit  vf  the  status  register  with  the  cniukitinn  bit  so  that  you  can  switch  between 
native  and  emulation  mode,  us  explained  earlier  in  this  chapter. 

Block  Move  In.Uructioni4 

•MVN       \in\f  bhick  in  negative  direttioii 
^M^P       Vinvt'  hlfick  in  positive  direction 

The  bluck  move  instruction!!!  are  powerful  instructions  thai  let  yiiu  transfer  d  hUxk 
of  data  trom  any  part  ul  menion.'  to  any  other  [dt  leaAt  ifynu  are  in  full  native  mnde). 
For  MVN,  X  and  V  must  LontLiin.  the  starting  addresses  tjf  the  sciurtc*  and  destination 
blocks;  the  [fnj;th  of  the  liliiek,  minu.s  one,  must  he  in  the  16-bit  C  rej;ister  (even 
iJ  the  m  tiaj;  is  not  0^,  The  source  and  destiniition  Iiank.'^  are  si^eeifiied  in  the  operand 
for  the  iiLStructiun.  MVN  moves  data  from  the  source  block  to  the  destination  block 
in  increasing  address  order. 

It  the  source  and  destination  blocks  uverlap  and  the  destination  block  begins  ilt 
A  higher  address,  dcJ  not  uSe  MVN,  beeauSe  the  end  of  the  suuree  liioek  will  he 
overwritten  before  its  data  is  moved,  In  this  situation,  use  the  MVP  instruetion 
iiLSttiid.  It  moves  data  innn  the  end  of  the  block  to  the  bej^iinninf;.  [Of  Ltmrae,  yon 
would  not  use  MVP  if  the  blocks  overlap  and  the  destination  block  begins  at  a  lower 
address, } 

To  use  MVN,  place  the  ending  address  of  the  source  ind  destination  blocks  in  X 
and  Y,  as  with  MVP,  the  cuutit  minus  one  j^oes  in  C. 

Flow-of-control  Instructions 

flCC  Branch  if  carry'  flag  is  clear 

BCS  Branch  if  carry  flag  is  set 

BEQ  Branch  if  zero  ll;ig  is  set  ie<|iial) 

BM  I  Branch  if  negative  flag  is  set  (niinusj 

BNE  Branch  it  zero  Hag  is  clear  {not  equal) 

BPL  Brtinch  if  negative  Hag  is  clear  (plus) 

BRA  Branch  always 

•BRL  Briioch  always  (loos  Torin) 
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BVC 

Branch  it'  overflow  flag  is  dear 

BVS 

Britiith  if  overflow  flap;  is  sc-l 

*  JML 

Juiiip  tij  luiip  address 

JMP 

Jump  t"  iilis^olutc  :iddress 

*JSL 

Jump  til  subrfflitint-  luiie,  saving  rrturn  iiddrt-ss 

JSR 

Jump  til  ^uliruulinf,  Si^vinj;  return  Liddiess 

«RTL 

KehirTi  from  subroutiiiP  InnR 

RTS 

Heturn  from  suliroutine 

Wlieii  thL'  l^Slfi  i-xciutes  n  procrsm,  it  Lisvially  prucesses  iustrutiioiis  in  the  ordi  r 
in  which  thev  Appc-iiT  in  tht  program.  You  eaii  uie  the  Huw  of  uoiitml  uistruLtions 
h,  tell  the  6581fi  to  jump  or  brLinch  to  any  piisition  in  ^  prusriim,  eillier  uTieoiidi- 
tioUiihv  or  uidy  if  a  eertain  mridition  is  true 

JMU  JMP.  BRA,  and  BRL  are  iinuunditlunal  in st ructions;  they  alwav'i  direct  the 
fiSSlfi  tn  dnolher  pnrtion  of  the  program.  JMP  transibrs  cuntrol  to  a  specific  memory 
address  BliA  imd  BRL  pi  rforiii  braneliiu^  relative  in  the  L-urrent  address  in  the 
program  ^otiuter.  The  ran^<^  uf  a  BRA  branch  -128  t«  +127  hytes  fmm  tlie  start 
of  the  next  instruction  in  the  program.  BRL  hrandie^  are  from  -3276^  m  +32767, 
su  vou  c:in  use  BRL  to  move  tu  any  part  of  the  current  program  hbuik. 

The  65816  also  -lupports  L^mditiontil  branihinn.  in  which  the  decision  on  whelhifr 
to  change  the  flnw  of  control  depends  on  the  ^eltiiig  oi  Htigs  in  the  statu.',  rtgister. 
These  are  the  Bt:C.  BC:S,  BEQ.  RMl,  BNE,  Bt^U  BVC.  and  BVS  iiihtrueUons. 
Use  them  aiter  anv  operatnun  ibat  afiecLs  tint  Hags  sci  that  you  can  take  diflercnt 
aotions  depending  un  the  result.  Refer  to  table  112-1  to  determine  how  eath  instruc- 
tion affects  ihe  prfH.-eisor  status  flans. 

For  exaniplt.  altera  CMP  (Ltimpare)  tommanci,  tliR  earr>'  llag  is  set  if  the  nLiinhcr 
in  [he  accumulator  is  greater  thun  or  e<iual  to  th<  number  in  the  operand.  Thus, 
you  c*mld  use  a  BCS  instruction  tn  transfi-r  coiiErnl  t^^  the  pnrtion  of  the  program 
that  <h>aU  with  this  situation. 

Ifa  program  needs  to  perform  the  same  task  again  and  aKain.  it  is  best  to  convrrt 
the  txsk  to  ii  callahle  ^uhriiutint'  so  that  its  code  clncs  not  have  tu  be  repeated.  To 
Lall  a  suliroiUitie  v.iu  can  use  the  JSR  or  JSL  iiihtriictiuns,  depending  on  whether 
the  subroutine  ends  with  RTS  or  RTL.  If  the  subroutine  is  ill  another  code  bunk, 
you  must  us^e  JSL, 

Both  JSR  and  JSL  push  on  the  stack  the  address,  minus  one,  of  the  next  instruc- 
tion in  the  program.  For  JSR  tins  is  an  ufTset  fn.ni  the  ^tart  of  the  current  program 
hank  (tv.u  byte;;);  fnr  JSL  it  is  a  long  absolute  jddrf  si^  tthree  bytes}.  The  subroutine 
must  end  with  either  an  RTS  instruetio!i  (if  called  with  JSI<)  ur  aji  RTL  mstrutlicin 
(if  tailed  with  JSL).  RTS  and  KTL  pop  the  return  addrest  put  on  the  ,^tack  by  JSR 
and  JSL.  put  it  in  the  program  counter  (JSL  also  updates  the  program  hank  register), 
and  iiicrenieiil  the  prugram  Lout.ter.  This  causes  execution  to  resume  at  the  instruc- 
tion following  the  JSR  or  JSL. 
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Arilhiirietic  Inslruelinns 

ADC      Add  inL-iiior>-  tu  aciiimuhiliir  with  uirry 
CMP       Ciimpliter  iit'L'iiiinil;iti>r  wUh  iiiL-mOA' 
CPX       Cnm[wrf  \  rt'Hister  with  uk-liion 
CPY       Com^wirc:'  \  ri-jibU  r  witli  jni  iniirv 
DEC       nt'LiL-nitTit  iht'  ui.i.11  nulla  tor  or  meiiuiry 
D£X       DcLTf^mi'iU  the  X  rc^islLT 
DEY       DtL-reineiif  llie  V  iriii:it<T 
INC       Incrtilieilt  thL'  attutnulLilor  or  nifitinry 
I  NX       IntrfiiiL-iit  thf  X  rcsi^itt-T 
[NY      hitre-iiietit  Hi*^  V  ri-eistLT 

SBC       Suhtratl  im-mi>n'  fmni  ac^-uniulator  with  L-arry 

Yiju  Vein  iisi-  INC,  I\X,  uinl  IN^  to  mtd  tmt"  to  the  \ahif  in  ihf  acL-uinuUh)i-  or  an 
index  K'Kisti-r.  (INC  iilsii  warb  with  inL-morv'  locations.)  The  lar^csl  number  a 
ref-ister  ciin  h»ld  is  SFF  (8  bit)  ur  $FFFF  U<3  bill:  the  rcfjister  mils  to  400  il  yo^^ 
iiiLreiiiellf  it  in  thrst-  sitiiatinns. 

Tlie  tfiTicspundni^i  deormu'nt  instrnetion>  arc  DEC.  BEX,  iind  DtlY.  ThfV  roll 
the  contents  of  the  n'j;iM*-r.s  haLWurds  tliroiitih  0  t..         ;S  bit)  or  ftFKFF  (Ifi  bill, 

You  can  iidd  or  siil>triict  iinmhers  other  than  iint'  Iroin  the  acti.mulalor  with  the 
ADC  iiiid  SBC  iii^^tiuctiiiiis.  Til  add  with  CLC.  you  must  remember  to  dear  the 
cany  llaji  Rrst  and  to  add  tnultiwurd  im  iiiiiltibvtet  niinibeTS  startini^  with  the  low- 
urder  wnrd.  For  {-iaintde,  In  add  $1ADSK  Lo  thr  Itnip  wurd  stored  from  Address  to 
Addre-'^s  +  :;i,  use  tode  like  this; 

CLC 

LDA  flddresa  ;[as5iiiinB  1G-bit  fl) 

ADC  •* 1 ftDBB  i low  word 

STfl  Addre55 

LOfl  ftddreas'2 

ADC  /"SIADBB  ; "  '  high  word 

STft  Addre35+2 

Siibtrafti«ni  is  similar  tn  addilio]!  fXCCpt  that  you  miisl  start  with  a  SEC  instruction 
befoi  t'  peribrriiinn    series  ol  SKC  opcnitinns. 

The  tompart-  tnstruetifms.  CMP,  CFK.  afid  Cl'V.  arc  really  subtraction  instruc- 
tions in  disRuise-  Tlie  diftVrt-nce  is  that  ihc  n-sult  of  the  subtraeti.jn  is  not  stored 
aimvhei  tlit  y  siiiipb  tiiunr  Haps  in  tht  stfltus  leHiJ^tt^r  to  change  depeiidin^i  on  the 
result.  Tlie  Bug  settinRS  are  as  follows: 

The  zero  flag  is  set  if  the  two  numbers  are  the  same. 

The  carry  Haff  is  set  it  the  {unsignerb  tnunbcT  in  the  register  is  greater  than  or 
the  same  as  the  number  bfiny  eompiired. 


The  65816  Jnstruciions  27 


The  carry  flap  is  clear  if  the  (unsigned]  tiumht^r  in  bhe  register  is  less  than  the 
number  lieing  compared. 

Ydu  can,  use  the  branch -oil-condition  instructions  to  change  the  flow  of  control  after 
a  cunipariiiQn  ppemlion. 

Logical  Inslructipns 

AMD      Logical  AND 

EDR      Logical  fxclnsiive-OR 

DRA       LoRical  OH 

Lugieal  inslruttioTis  combine  tlip  value  in  the  attumuUtor  with  the  value  in  the 
nperand  in  atcnrdancc  with  the  rules  of  BiKik an  algebra.  The  result  is  stored  in  the 
at'cnmulatar. 

For  AND  operations,  all  hit.^  in  the  accumulator  that  correspond  tu  0  bits  in  tW 
operand  are  cleared  to  0:  other  bits  arc  miaflected.  With  ORA,  all  hits  in  the 
operand  that  cfirrespond  to  1  hits  in  operand  arc  ^et  to  I.  other  bits  are 
i:naJ!eLted.  Tlie  EOK  oiieration  ih  more  cnmpli<:ated  than  either  AXD  or  OR^^.  It 
M-ts  to  1  all  hit^  that  are  I  in  the  accumulator  and  0  in  the  operand  or  vice-versa, 
Bits  that  are  the  same  in  value  are  cleared  to  0. 

Bit -manipulation  Instructions 

B  I  T      Test  bits 

TRB       Test  and  reset  hiis 

TSB       Test  and  set  hits 

The  BIT  instructlcm  performs  two  functions  at  once.  First,  it  tfansfcrs  the  high- 
order  t\w  hits  of  the  operand  to  the  nesative  and  overliow  fla^s  in  the  status  register 
(but  only  if  the  operand  is  not  an  immediate  number).  If  the.^e  two  bits  store  program 
flags,  you  cin  follow  the  BIT  with  BMl  to  hrancK  if  the  hi^h-order  hit  is  set.  or 
with  BVS  ii  tlie  next -to-high -order  hit  is  set. 

The  second  function  of  BIT  is  to  logically  AND  the  contents  of  the  sct^umulator 
with  the  value  of  the  operand.  The  result  is  not  stored,  hut  the  zero  flag  is  condi- 
tioned hv  the  operation.  This  is  a  handy  way  of  deterniininy;  if  certain  hits  are  clear 
oi  set  without  destroyinp  the  contents  of  the  aceumulator  For  example,  to  test  bits 
0  and  1.  use  the  instruction: 

BIT  •S00D0001 1 

If  eidier  of  tho  last  two  hits  in  the  aceumulator  are  1,  the  zero  9ag  is  not  set  and  a 
Subsequent  BKE  branch  will  succeed. 

You  can  set  or  clear  any  group  of  bits  in  an  operand  wilh  the  TRB  and  TSB 
instructions.  TllB  clears  to  0  those  bits  in  the  operand  that  correspond  to  1  bits  jn 
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the  aec'umulatnr.  Conversely,  TSB  sets  these  bits  la  1.  TRB  and  TSB  also  IrjgiDally 
AN  D  the  aft'Diiiulatfir  with  the  operand  and  set  the  zero  Has  ac'cortling  to  the  result, 
The  result  itself  is  imt  stvmd. 

SEiift-ancJ-rotate  InstruQtions 

P»SL      Arit hint- tic  ;;liift  left 
LSR      Logical  shill  riglit 
RDL       Rotate  left 
ROR      Rotate  right 

The  shift  and  rotate  itistnictions  let  yoi)  manipulate  the  bits  in  the  accumulator  or 
in  ti  mcnion,-  location  hy  sliifting  thein  left  or  right. 

ASL  moves  tbv  bits  in  the  optrrand  one  position  to  the  left.  The  high-order  bit 
moves  into  the  L'arr\'  flag  «f  the  status  register  and  a  0  appears  in  bit  0  of  the 
operand,  ROL  is  the  same  as  ASL,  except  that  it  is  the  initia]  value  of  the  carry  flag 
that  is  put  in  hit  G. 

LSR  moves  bits  in  the  operand  cme  pcisition  to  the  right,  with  bit  0  moving  into 
the  carry  flag.  A  0  appears  in  the  hif;h-nrder  hit  nf  the  operand.  ROR  is  the  same, 
except  that  the  initial  value  uf  the  ^.■a^^^■  Hag  is  pnt  in  the  high-nrdcr  bit. 

Tlie  operand  size  for  shift  and  rotate  instruction*  is  cither  fi  bits  or  16  bits^ 
depending  oti  the  status  of  the  m  bit  in  the  status  register. 


System-control  Instructions 


BRK 

break  [iuftware  interrupt) 

RTI 

Return  from  interrupt 

NOP 

No  operation 

SEC 

Set  carry  flag 

CLC 

Clear  carry  fla^ 

SED 

Set  decimal  flag 

CLD 

(Hear  decimal  flag 

SEI 

Set  intfrrupl  flag 

CLI 

CUi'ar  Interrupt  flag 

CLV 

Clear  overfltiw  flag 

"SEP 

Set  status  register  bits 

tCEP 

Reset  statui  rcf^ister  hits 

-COP 

Co-i)nicesM>r  [software  interrtipt) 

«STP 

Slop  the  cluck 

•  UIAI 

Wnit  for  interrupt 

-UIDM 

[Reserved  for  expansion] 

The  system  control  instructions  perform  a  variety  of  miscellaiieous  operaitions.  One 
group  [SEC,  CLC,  SKD.  CLD.  SEI.  CLI.  CLV.  SEP.  and  REP)  can  be  used  to 
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cspUcitlv  set  or  clear  bits  in  the  status  register.  The  main  use  of  SEP  and  REP  is 
tci  net  aiid  clear  the  m  and  x  bits  in  the  status  repistf^,  as  explained  above. 

NOP  is  a"clo-nQthinil  '  instruc-tmn  that  simpK  acts  as  a  placer-holder  in  a  dehusginj! 
operation  or  a  titne-waster  in  a  timing  loop. 

STP,  WAI,  and  WDM  are  insliuctions  yim  will  probably  never  need  to  use.  STP 
essentially  shuts  down  the  65816  until  a  system  rc^et  occurs.  WAI  puts  the  6^16 
into  a  Inw-povver  mode  aod  then  wails  until  a  6.^^16  interrupt  (jtcurs  hi-foie  passing 
control  to  the  ncft  instruction  in  the  program-  The  WDM  instruction  is  reserved 
for  future  expansion  of  the  65^16  itistruetiou  sH. 

The  BKK.  COP,  and  RTI  instructions  are  related  Co  &5«I6  interrupts  and  will  be 
discussed  later  in  thii  chapter. 

THE  65816  ADDRESSING  MODES 

An  addressing  mode  de^ierihes  the  technique  the  65S16  uses  to  locate  the  data  with 
which  an  instTuttion  needs  to  work.  In  a  65^16  program  soviTce  file,  the  addressing 
mode  information  appears  in  tht-  operand  field,  just  after  the  instruction  mnemonic. 
The  assembler  format  for  each  addressing  mude  is  shuwn  in  table  2^1- 

Kaov-ing  die  addressing  mode,  the  fi5816  can  use  the  operand  to  calculate  an 
effective  address  (EA)  fur  the  instruction.  For  read  operations,  the  EA  is  the  address 
from  which  data  is  read:  for  write  operatiims,  it  is  where  d&ta  is  stored.  The  effective 
address  t^alculation  varies  with  the  addressing  mode,  af  wurse:  it  may  he  a  simple 
absolute  addres.^,  an  addrt-ss  calculated  by  addins^  the  contents  of  the  X  register  to 
a  base  address,  an  address  pointed  tu  by  two  locations  in  direct  pdge,  and  so  on. 
The  availability  of  so  many  different  addressing!  modes  makes  it  easier  to  develop 
efficient  program.'^. 

This  section  investigates  the  variuus  addressing  mcjdes  you  can  use  with  the 
65S16.  Keep  in  mind,  however,  that  not  all  addres^in]^  modes  can  be  used  with 
every  instruction.  To  see  if  a  particular  mmbination  is  permitted,  refer  to  table 
R!3-l. 

Imphed 

Many  instmetions  do  not  require  an  explicit  indication  of  addre.ssing  mode  because 
the  instruction  mnemoiiir  completely  describes  what  needs  to  be  done.  These 
instructions  use  the  implied  addressing  mode. 
Examples  of  such  instructions  are  as  follows: 


5ED 

NOP 

TAX 

TSX 

MAI 

CLy 

CLD 

TRY 

TXfl 

WDM 

SEI 

CLI 

TCD 

T(5 

CLC 

SEC 

TC5 

TXY 

INK 

INY 

TDC 

TXA 

DEX 

DEY 

TSC 

TYA 

This  list  includes  every  instruction  that  eitplicitly  sets  or  clears  specific  status  flags. 
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Table  2-|;     The  Assembler  PDnnats  of  the  65616  Addressing  Mndes 


Assembler 

Name  of  Atidressina  Mode 

Fonnat 

Implied 

Accumuklur 

A 

Imni'ediate 

V  i  in  Tti  fill  iiVi^ 

FrHgram  Counter  Relative 

rel 

'Program  CoLinter  Relative  Long 

In  ly.  crr^l 

Stack 

'Stack  Relative 

sr  S- 

*Stack  Relative  Indirect  Indexed  with  Y 

(sr  S)  Y 

"Block  Move 

kll  VU]ll\i  U^iJ  K  Lr  lin 

Absolute 

addr 

Absolute  Indirect 

(addr) 

Absolute  Indexed  \Wth  X 

addr.X 

Absolute  Indexed  with  Y 

af\i\r  V 
■i^iiil  .  1 

Absolute  Indexed  Indirect 

(addr.X) 

*  Absolute  Lung 

long 

"Absolute  Long  Indexed  with  X 

long,X 

*Absolyle  Indirect  Long 

[addr] 

Direct  Pafje 

dp 

Direct  PaRe  Indirect 

[dp) 

Direct  Page  Indexed  with  X 

dp,X 

Direct  Page  Indexed  with  Y 

dp,Y 

Direct  Page  Indirect  Indexed  with  Y 

(dp),Y 
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Table  2—1;     Cimliiiuf  d 


Assembler 

?iamc  of  Addresfiiiia  Mude  ffninit 

Direct  Page  Fndcxcd  Indirect  wibh  X  (dp,X) 
"Direct  Page  Indirect  Long  [dp] 
^Direct  Pa^e  liidirett  Long  Indexed        Y  [dp],Y 


A  =  acL'umululor  li>ii!;j"i"[  ~  U>l'pl  nflsi't  iiddress 

Luidr  =  Ifi-bit  iLiidrt's.'i  tiuiiiIrt  =  fS-  or  l6-!iit  >CDiistii3it 

(lesdink  =  hiink  tiiiiiiIk't  k^I  =  S-lnil  offset  addrL'sN 

dp  =  dircc't  pa^e  iiddress  st  =  stack  pdinte-r  iiftset 

loriH  —  24-bil  address  srtbnk  =  bank  number 

vt'TE:  AtidrcisinK  nnxltrs  in)l  supported  hy  ihv  d^CIIg  an'  niarkt'd  nirh  asft  risks. 


Ai-cumulatnr  A 

Tbe  LiL'cii:nidy.l:iii"  Liddrcs^inj;  mode  is  iispti  liv  !hn:se  instniL'titm-i  lhat  iiiilinpulate  the 
cuntt'nts  (jf  tht'  atomiiidiLtiir  liut  that  do  mit  need  tu  be  isiipplied  with  an  address  or 
d&tA.  Here  are  stJine  examples: 


L5E  ROL 
flSL  ROR 
INC  DEC 


To  select  this  addrejising  mnde,  put  the  letter  A  1ii  the  operand  field. 


Immediate  #imniediate 

The  imint'diate  addressing  mode  is  used  when  the  operand  Is  a  numeric  constant- 
The  ;issc'ml>]er  larmat  for  this  iniidc  is  #ii]inn'diiU<-  That  is,  precede  the  number 
[«r  a  symlxil  for  a  nuinbt'r)  witli  the  #  symbol. 
Here  are  snnie  examples: 


LDA  #23  ;Decliral  numbec 

LDK  HtfilF^  ;HeM    numbiers  begin  wiLh  i 

CMP  #^000001  1  0  ;Biriary  numbers  begin  with  S 

ADC  #?5e 
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Do  not  forget  to  include  the  #  symbol  when  using  lliis  mode.  If  yim  do  forget,  tlie 
assejnblci  thinks  you  are  reftrrioK  to  an  address  and  will  cleal  with  the  number  at 
that  address,  nut  the  constaot  itself. 

Progi-Am  Counter  RetaEive 

This  addrpssing  mode  is  used  h>  the  fi^8Ifi  liranch-on-ajiidilion  instructiims:  BCC, 
BCS,  BE(^.  BMl,  BNE.  BI^L.  BJU.  B\  (:.  and  BVS,  Fdr  this  mode,  the  i>peiand 
represents  the  offset  to  a  target  address,  rneasorf  d  from  the  instrucCioo  following 
the  braiicti  instruction  Thts  ofl'set  must  be  a  ^i^nril  \\i]up  frnm  -128  tu  +127, 
Transterrin^  Ltrntrol  to  a  target  outside  this  range  iM  passihle  orjly  w  ith  uneooditi()nal 
JMP  or  BRL  instructions. 

When  nsinj;  this  modr.  it  is  not  necessarv  fur  ymi  to  caleidale  tlie  offset.  Simpiv 
specify  tlie  addres.s  of  the  target  lot-ation  in  tlie  operand  field  of  the  instrlietitm  by 
Tefbm'ng  to  its  label,  ^s  folbw^: 

BCC       MyTarget        ■lEranch   to   labelled  address 
MyTarg^t  NDP 

The  assembler  cak-ulates  tKe  offset  for  you  when  assembling  the  file. 
Program  Counter  Relative  Lon^^ 

This  atldressing  mode  is  used  by  the  BRL  and  PER  instrutrtions  only,  For  this  mode, 
the  operand  i^i  an  offset  from  the  start  of  thf  tnllowing  instnietion  to  a  tarjiet  address. 
Tlie  offset  range  is  from  -3276fi  to  i-3r27fi7,  so  you  can  aLcess  any  location  in  the 
current  bank.  (Wraparound  within  a  hank  occurs  if  the  offset  is  past  the  end  of  a 
bank.) 

As  with  the  program  counter  relative  mode,  yon  need  oidy  spetih-  j.  target  address 
when  Writing  a  program,  the  assembler  will  eaJtulate  the  attual  uHset  for  you. 

Stack 

The  staek  addrpssiuR  mode  is  really  a  variation  of  the  implied  mode.  Iieeau,'>e  the 
instruction  mnenmuic  coinpleteh'  deSL'ril>t\s  the  operation.  For  push  in-itrnctions, 
this  mode  causes  data  to  he  added  to  the  tnp  of  the  statk  and  the  staek  pointer  to 
be  decremented  by  the  size  of  tile  data,  I-'or  pull  instrnctiotis.  data  is  taken  from 
the  top  of  the  stack  and  tht  statk  pointer  is  intrenietited, 

Staclc  Relative  ir,S 

A  raminon  techniipie  for  passing  parameteris  tu  [s  subroutine  is  to  place  the  param- 
eters on  the  stack  prior  To  csmrliog  the  JSR  (tr  JSL  instrutlion.  As  the  oe\t  chapter 
will  mver,  (his  is  the  technique  you  will  use  when  calling  GS  tool  set  functions. 


Thf  e5S16  Adfire.-isinp:  Modes  33 


An  easy  wav  lu  rotrit-ve  paraint^lers  piL-;s<.cl  on  llif  slatk.  or  Ui  return  iKiramcters 
in  the  slsct;,  is  to  us.-  lh<-  stiitk  relative  atlilriSHiie  mode,  Willi  this  mode,  ymi 
.^pccift  a  nnt-  byte  iiuihIht  from  S(XI  tu  SFF:  the  (>ri>iIH  udtls  this  number  tn  the 
contc^nls  nf  the  slack  pointf  r  to  (iLlcrmhie  lli<-  elloctivi-  address. 

Suppose  a  program  calls  a  siibrontiiie  by  pushing  nm;  word  ui  data  on  the  stick 
before  the  JSR.  When  the  subroutine  gt-ts  control,  the  stack  loolts  like  this: 


SP 


parameter 


return  address 


SP+3 
SP+I 


To  ai^ess  ihe  parameter,  use  the  tbllowinR  instmctinn: 
LDA  Sa3,S 

The  offset  from  the  Ntatk  pointer  is  $03.  because  SP  pointi  In  the  iiddr(  ss  just  below 
the  JSR  ri-tnni  Llddv.-ss.  anil  the  rc-turr.  .iddrcss  is  t%vo  bytes  lonj;,  If  the  siibroutnie 
had  been  i:aUed  with  a  JSL  iiistruetion,  the  oHsct  would  he  m  because  a  loag 
return  address  is  three  bytes  long. 

\otc  thiit  if  the  subrnutine  pushes  any  data  im  the  stack  alter  jieltlng  control, 
the  offset  til  the  piirainetpr  must  be  itdjusU'd  accordingly, 

Slack  Relative  Indirect  Indexed  with  T  (sr.SLY 

This  addre^sinft  inude  it;  visi  M  if  the  staek  t^ntains  a  pointer  to  d  data  structure  in 
the  fiirrent  data  hai.k.  Hy  speeityinji  a  stack  iifiset  from  $fH)  to  SFF  and  loadinfi  the 
Y  reg;istcr  with  an  offset  into  the  data  structure,  you  can  access  any  field  in  (he  data 

structvirc.  i      a-  . 

The  a^^sembler  format  Tor  this  mode  is  (sr.SlY-  Tlie  65Hie  calculates  the  effective 
address  by  first  adding  sr  to  S.  It  then  lakes  the  pointer  stored  ^t  thai  address  and 
adds  to  it  the  value  !ilorrcl  in  tlic  Y  register 

One  dirticLiltv  with  thij^  Tiindc  is  that  it  does  not  work  with  long  (24-bit)  address 
pointers,  and  fhe^e  arr  the  lyp^s  of  point*=rs  parsed  Lu  GS  tool  set  funtlions.  In  this 
situation  it  is  better  to  use  the  direct  pat;e  indirect  lonfj  indexed  with  V  addressing 
mode  (see  below).  You  can  do  this  by  deficiinS  a  n^w  direct  page  that  begins  at  the 
base  of  the  stack. 

Block  Move  srcbnk,deslbilk 

This  addressing  mode  is  usecl  onlv  by  the  MVN  and  MVP  block  move  instructions 
The  form  of  the  operand  is  two  luiik  immlters  separated  by  a  romnia;  the  first  bank 
is  the  bank  for  the  source  block  and  the  .second  is  the  bank  for  the  destination  block. 
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Absolute  Addre^sin^  Modes 

Absolute  addr 
Al)so1utt.'  Lun^  addr~ 
Direct  Papt."  dp 

The  efFeftive  adilresh  l(}r  llie  ahiolutp  addressint;  iiiudf  is  tKt^  16-bit  address  dehnKcl 
by  the  label  in  the  iipereiiid  field.  The  fi5ti\6  Ibrni:;  the  effective  24-bit  address  by 
eiiiiibiitiri^  this  :iddre.sh  witli  the  nuiiiher  in  the  prupraiii  liaiik  repiiiler, 
Here  ure  some  e.\aiu[jles  oi  tlie  dbsiilute  addrenisin^  iiiude: 

tDfl  tflyData 
STX  TheRcBiilt 
RQL  BitFlaga 

In  oath  Ciisc.  the  operand  field  contains  a  symbolic  label  for  th*'  address 

When  using  the  uhsoliitp  addressing  mnde,  it  is  very  important  to  ensure  diat 
the  data  bank  register  is  the  s;imp  as  the  program  hank  register,  at  least  if  the  laheb 
refer  to  offsrts  into  the  program  bank  (the  UKiial  vdnf).  The  casit  st  way  to  dn  this  ii* 
to  eseciitt  PHK.  PLB  instruttioii.s  al  the  beginning  n(  the  pro;(rani. 

IF  the  data  bank  register  is  not  set  up  properly,  you  must  use  the  absolute  long 
addrcssins  mode,  in  this  'iitunlinn.  thr-  efibttive  address  ii<  ihp  S4-bit  addrE-ss  spct- 
ified  in  the  operand:  the  data  bank  register  is  not  referenced.  MhsI  as^iemblerK, 
inchiding  Apple  s  APW  assembler,  default  to  absnbite  addressing  if  they  eannot  tell 
if  the  address  is  long  (24-bit)  or  normal  ilfi-bit).  To  force  absolute  long  addressing,, 
put  a  "-■  syinbol  in  frunt  of  the  address. 

If  the  operand  is  a  location  in  direct  page,  you  can  use  the  direct  page  uddres^ing 
mode  instead  of  absoJule  or  absolute  long, 


Absolute  Indexed  Addressing  Modes 

Absolute  indexed  vvith  X  addr  ,  X 

Absolute  indexed  vvith  Y  addr  ,Y 

Absolute  loiiE  indexed  with  \      abbaddr  ,  X 
Dirett  pa^e  indexed  with  \         d  p  ,  X 
Direct  page  indexed  with  Y         dp  ,  Y 

These  indexed  addressing  modes  are  the  same  as  the  corresponding;  unindexed 
addressing  modes.  e.Mt'pt  tliat  the  f>.'581Ci  add.s  the  content*  of  iui  indes  register  In 
ihf  specified  address  to  fonii  the  effective  address.  Here  are  some  examples; 


LDfl 

Ta  5  l(  Recc  rd  ,  X 

;EA  = 

Ta  5  kRecord*  K 

STfl 

MyF  i  eld , V 

iEA  = 

LDfi 

(El  aOOQ  ,  )C 

;Efl  = 

IE1  □aao'-x 

5Tft 

S3?,  « 

;e:a  = 

LDX 

sie,  V 

;Efl  - 
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Use  these  modes  tu  step  into  the  data  structure  beginning  at  the  base  iiddress,  The 
base  aJdrt-ss  i-;  c  illitr  a  Ifi-bit  address  (addr^  a  24-bit  address  (aKsaddrl.  or  a  direct 
pa^e  address  (dp). 

Indirect  Addressing  Modes 

There  are  eijE^ht  dlflfereiit  indiri^ct  addressinp  mtidrs  you  can  use  to  access  a  data 
stnictiire  whose  addrt'Si  is  pa^ist^d  tn  you  aa  a  paramctpr 

Dir<?ct  p»ge  indirect  C  ) 

Diriiitt  page  icidirecl  long  [  dp  ] 

AhsnliJte  iiidirecl  (addr  ) 

AhMilute  itidirect  loiii;  [addr  ] 

Ah.st)liite  indexed  indir-ect  f  a  dd  r  ,  X  ) 

Direct  page  indexed  indirect  witli  X  f  dp  ,  X  ) 

Direct  page  iiidireet  indcved  with  Y  f  dp  )  ,  Y 

Direct  page  iiidiirect  bng  indexed  with  Y       C  dp  ]  ,  Y 

If  you  know  Ihe  absulutc  position  in  memory  of  the  data  structurt-,  you  can  use  n 
direct  addressing  mode  instead  of  an  indirect  addressing  mode. 

The  indirect  addressing;  modes  all  involve  address  pointers  that  are  two  (normal) 
or  three  (lon^)  byles  in  length.  These  pointers  are  stored  in  memory  with  the  low- 
order  byte  or  bytes  first. 

The  indirect  modes  whieh  iwe  nondirect  pa^e  addresses  for  storing  the  pointers 
work  widi  JMP  and  JSiH  instructions  only; 

JMP    (addr)  ;  16-ibi.l  pointer 

JMP  laddrJ  ;loTig  pointer 

(flddr,)()  j15-bil  pointer 

JSR  (addr,!()  ;IG-bil  pointer 

For  these  rntxlcs.  addr  is  the  address  at  which  the  pointer  to  the  data  stnicture  is 
stored,  For  (addr)  and  [addr]  modics,  this  address  mnitt  be  in  bank  $00. 

The  [addr,Xl  mode  is  often  used  to  pass  cimtrol  to  a  5.1  ibrou tine  whose  address  is 
in  a  table  nf  subroutine  addresses  beginning  at  addr.  By  putting  the  relative  position 
of  the  subroutine  address  in  X,  you  tan  call  the  subroutine  with  JSR  [addr,X)  or 
JMP  (addr,X).  That  h  because  tin-  fi5f>16  forms  the  effectlvti'  address  by  adding  the 
value  in  the  X  register  to  the  address  specified  in  the  operand. 

For  the  other  live  indirect  addressing  mode^,  the  pouiter  must  be  in  a  direct 
page  loeatiun.  The  clVeetive  addresses  are  ealcnlated  as  follows; 


(  dp  )  EA  =  the  address  stored  at  dp/dp+1 

(  dp  ]  EA  ^  the  address  stored  at  dp/dp+  l/dp  +  2 

{  dp  )  ,  Y       EA  =  the  address  stored  al  dp/dp+1  plus  Y 
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[  dp  ]  ,  Y  l£A  ^  ihe  address  stored  M  dp/dp+  l/dp+2  pliu  Y 
{  dp  ,  y  )       KA  ^  fill'  iiddrf-ss  stored  at  dp+X/dp  +  X+1 


jV(*/(V  Thi-  ellt-t'livi-  addresses  urc  uddrrLSse-is  in  Ihc  hank  Mtorc-d  in  llic  data  ijiuik 

L'Sf  thf  (dp)  or  |dp]  ni  (dp, XI  nuidi's  if  y<Mi  need  tti  -.ivcvss  only  iti*"  first  byte  (S- 
liit  register!  or  ward  ilti-ttit  re;!:ist<'r)  of  the  ilatj  .stnittiirt'.  To  TiiLiiupulLitE!  other 
['xirtions  of  a  c!ati4  structure',  ymi  iniist  use  ([lpl,Y  or  |dp|.V  itlter  setting  llie  Y  register 
to  the  apjiropriati'  vahir. 

The  |dp].Y  iidtlri-ssiiia  mtide  is  usfful  lor  dt:fessiiij;  data  ilrUL'turei  whose  long 
pi>iiiters  are  passed  tlu'  staek  (o  a.  suh routine.  Here  is  an  exLiniplt'  of  ii  suhroiitirie 
thai  stores  a  result  in  by  li  s  ^k20/^i2l  of  .i  data  strui  ture  ivliohc  address  is  puslied  on 
the  stack  before  the  snlirontine  is  Lalled  with  JSL: 


;  3 
PHD 
TSC 
TCD 
LDA 
LDV 
STB 
PLD 
RTL 


by  tea   at    tcp    of    *taci:    on   entry    (from  JSL) 

;Saue  d.p.   register   {add^  2  to  SP) 


=   5  tsc  k    po 1 nter 

to  return 


;hBk»  direct  page 

#»SCIOO  ;Thi5    15   the  ualu 

#2Q  ;4Gce«  S        t  h    by  It 

[SQBJI.Y  ;5lore   the   result  ^  S'^.l 

iRestorp  original  direct  pagt 
;  (Sub  cat  led       tti  J5L> 


Rather  than  remove  the  pointer  frcn-n  the  staek  and  piil  it  in  the  tiirreut  direct  page, 
this  sotiroiitinr  dehiies  a  new  direc  t  patje  that  hejjiiis  at  the  address  stnred  in  the 
staek  pointer.  BecausL'  this  oltois  idler  the  PI  ID  ioitroelioii,  the  direct  page  addrew 
of  the  staek  jjiiraineter  ih  SOfi:  the  [una  return  address  (pushed  on  the  stack  by  JSL) 
is  at  S03-ai05.  and  the  copy  ill  the  direct  pa^e  reeister  is  at  S()M<1)2. 


LMERRLTTS 

An  interrupt  Is  an  eleelrunic  .'Signal  that  demands  the  immediate  attention  of  the 
microprocessor  The  signiiil  can  originate  from  either  a  hardware  device  or  a  pro- 
gramining  instruction.  The  four  hasie  ty^ies  of  hardware  interrupts  are: 


»  IR(^  (interrupt  recjue&t) 

•  NMI  (nnninaskable  interrupt) 

•  Reset 

•  Ahort 
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The  two  types  of  software  internipts  are: 


«  BRK  (break) 

•  COP  {co-processor) 

Thii  spctinn  takes  a  look  at  huw  the  65816  deals  with  intemipts. 
The  IRQ  Hardware  Interrupt 

All  IHy  hardware  interrupt  is  an  electrical  signal  from  a  peripheral  device  that 
activates  the:  IRQ  (interrupt  request)  pin  (in  the  65816,  When  Iht-  a'^Hlfi  senses  an 
active  IH9  sifjnal.  it  stups  executing  the  current  program  and  switches  to  another 
proRram.  (.'ailed  an  interrupt  handler,  to  deal  with  the  sourte  uf  the  interrupt  When 
the  handler  ends,  cnnlrol  returns  tu  ttie  original  program  and  execution  cniitinues. 

It  is  easier  for  a  program  to  deal  with  input  devices  tliat  inttrrupt  the  system 
because  there  is  less  risk  of  misshiR  intomliiK  data.  If  the  device  does  not  interrupt, 
the  prugram  must  periodically  check  its  status  to  see  if  the  device  ha.5  data  ready. 
If  the  profrram  docs  not  check  often  enoujj;h  (perhaps  hecause  it  is  eseeuting  a  time- 
consuming  snbrontine).  it  will  get  behind  and  lose  data. 

Some  of  the  bnuree-i  ol  IRQ  hiterrupti,  on  thi;  GR  are  the  seriiil  ports,  the  mouse, 
the  keyboard,  the  deck,  the  video  c-untroller,  and  the  Ensoniq  DOC.  The  serial 
ports,  lor  example,  can  he  programmed  tu  fjencratc  interrupts  when  they  receive 
data.  The  interrupt  handler  will  then  read  the  data  and  store  it  in  a  buffer  so  that 
it  cnuld  be  retrie\  ed  by  the  program  when  it  is  ri-ariy  for  more  input. 

If  you  set  the  interrupt  disable  flag  in  the  65HIfi  status  register,  the  65H16  will 
ignore  IRQ  inten-upt.-;.  You  may  want  to  do  thi.s  if  your  program  h  in  the  middle  of 
a  critical  timing  Inop  or  if  the  program  is  nut  re-entrant  (capable  of  beinj;  called 
wbiEe  It  is  in  use)  and  there  is  a  possibility  the  interrupt  handler  may  call  the 
program  recursively.  In  j;pneral.  interrupts  should  be  left  on  at  all  other  times. 

When  an  IRQ  interrupt  tKCurs,  the  (i58I6  lakes  one  of  two  actions,  depending 
On  it,';  current  mode.  In  native  mode.  It  pushes  the  program  bank  register,  the 
program  counter,  and  the  .'Status  register  on  the  stat-k.  In  emulation  mode,  only  the 
program  counter  and  the  status  register  are  pushed.  Then  the  6SS16  clears  the 
decimal  mode  flag  in  the  status  regj.'^ter  and  sets  the  interrupt  disable  flag  so  that 
nothing  will  interrupt  the  interrupt-handtiilg  subroutine.  Finally,  the  65816  passes 
control  to  a  vector  in  bank  $1)0  associated  with  IRQ  interrupts.  As  .shown  in  table 
2-2,  the  position  of  this  vector  depends  nii  the  operating  mode  The  interrupt 
handler  ultimately  passes  contru!  to  a  user  vector  at  S3FE/S3FF  in  bank  SOO — that 
is^  if  control  Is  not  handled  internally. 

An  interrupt  handler  must  t-nd  with  an  RTI  instruction  because  RTI  pops  the 
values  pushed  on  the  stack  when  interrupt  pi-ocessinp  begins.  Because  only  the 
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Tabic  2-2:    65S16  Interrupt  Vectors 


EmuSatiun  Mailf 

Native  Made 

Vectors 

SOOFFFE/FF 

IKQ,  IJKK 

$nOFFEE/EF 

$W)FFFC/FD 

Reset 

$fK)FFl-A/EB 

NMI 

$OOFFRVFB 

NMl 

I00FFES/E9 

Aburt 

S0OFFF«/F9 

Abort 

SlKlFFEfVET 

BKK 

SOOFFF4yF5 

COP 

S(I0FFE4/E5 

COP 

SOOFFFC/FD 

Reset 

program  tounter  and  the  status  rngistcr  are  saved  on  the  stock,  the  interrupt  handler 
must  preserve  the  Ktates  of  the;  other  6.5816  registers  il  alters. 

Tlie  preferred  way  to  inMtdll  iiitrn-iipt  handlers  in  a  ProDOS  envininment  is  to 
use  the  ProDOS  ALLOC;— INTERRUPT  cominand.  (See  cliapter  Ifl.)  In  these  ciseii 
the  interrupt  handler  dues  not  have  to  preserve  registers  and  can  end  with  an  RTS 
[ProDOS  S)  or  KTL  [ProDOS  16)  inMrnction.  This  is  because  the  internal  ProDOS 
interrupt  dispatther  takes,  eare  ol  saving  registers  and  returning  control  properly. 

Other  Hardware  Interrupts 

Devices  can  sdso  generate  NMls  [nonmaskable  interruptsj.  The  fiSRIfi  hbinflles  them 
just  like  IRQs  except  that  it  uses  a  different  interrupt  vector  and  it  never  ignores 
them  even  if  the  interrupt  disable  llag  ib  set.  A  peripheral  might  tausc  an  NMI  if 
i{  has  to  take  nver  the  system  In  an  ecjiergeiley  situation,  sueh  an  an  impending  loss 
of  power.  The  N  \1 1  interrupt  handler  iti  the  cy  eventually  passes  mntrni  to  a  user- 
installed  subroutine  who.se  address  is  stored  .it  S3FC/|3FD  in  bnnk  $00. 

A  Reset  interrupt  occurs  when  you  turn  the  cs  on  or  when  you  press  Control- 
Reset.  When  Reset  is  caused  by  the  power  turning  an,  the  system  boots  the  start- 
np  disk  When  ]>ower  is  turned  nn.  Resets  are  handled  by  eventually  pa.ssins  centrol 
to  the  subroutine  whost  address  is  stored  at  S3F2/S3F3.  to  bank  SiOO,  but  only  if  the 
byte  at  S3F4  is  equal  to  the  number  gcmerated  by  exclusive-ORinj^  die  number  at 
$3F3  with  the  constant  $A5,  If  it  in  not,  the  system  is  rebooted  instead. 

The  last  type  of  hardware  interrupt  i.s  the  Alport  intorrnpt.  It  is  supposed  to  be 
generated  by  a  hardware  memory-management  unit  when  i(  delects  a  program 
lr^'ing  to  access  njemor^'  that  is  iiff-limit\  to  it.  On  the  cs,  only  cards  installed  in 
the  niemorv'  expansion  slot  can  generate  Aburt  interrupts. 

The  addresses  of  the  vectors  for  NMI,  Reset,  and  Abort  interrupts  are  shown  in 
table  2^2. 
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Software  Interrupts 

You  can  also  gcn»^rate  iiUerrupt  signals  by  excrutins  a  BRK  or  COP  instniction 
inside  a  program,  The  65S16  rt^acts  !o  sulIi  intcmipl  nigiiiJs  just  it  rt^atts  hi  an 
active  IRQ  signal,  hul  il  uses  a  diffcrf'nt  intornipt  vfclor  Nt-ilher  the  BHK  nor  the 
COP  in!itrui;tii)n  ta.ii  he  iim.'.kt'Ll  by  thr  interrupt  dibablo  fi:iK  in  the  status  register. 

BBK  and  COP  have  ^rparatL'  intrri  upL  vectors  hut  arc  handled  in  iiiiich  the-  same 
way  by  the  mtjuitor.  (The  COP  instruction  was  desi^^ntd  to  pass  tontrcil  to  a 
RfiHie  L-oproc(-s,sor  chip,  but  such  a  tliip  is  not  available  yet.)  When  you  start  up 
ProDOS  S,  however  hoth  vectors  eventually  pass  lontrol  to  the  same  RAM  vector 
Bt  g>3F(J/$3FI  in  hank  SCHI.  Thi!i  vpttur  pninls  to  a  inoiiitor  siilirnutiiie  that  displays 
the  etmlents  uf  the  b.>S16  reRistrrs. 

BRK  and  COP  aro  hntli  two-hvte  iii^fruetuni!!  even  thtiugh  the  second  byte  has 
nu  particular  meaning.  The  BRK  or  COP  handler  ynii  install  can  examine  the  second 
hyte  and  inteqiret  it  any  way  it  wishes,  It  is  essentially  a  parameter  that  is  passed 
to  the  handler 

Note  that  in  tmiilatiuii  mode,  BHK  and  IRQ  interrupts  share  the  same  mtetmpt 
vector-  Tu  distiii^uish  belAvccn  them,  the  system  examine.'^  the  break  hit  in  the 
status  register;  if  it  is  1,  iho  internipt  was  l;uisc{1  by  a  BRK  iiistructinu  mid  thi^  cs 
monitor  parses  control  to  the  vectut  stored  at  $3FO/5i3Fl  instead  of  to  that  at  $3Fi:/ 
$3FF. 

CRFATING  PROGRAMS  WITH  THE  APPLE  IlGS 
PROCRAMMER  S  WORKSHOP 

The  Apple  Hgs  Programmers  Workshop  (APW)  contains  all  the  programs  and 
support  files  ynu  will  nrcd  to  develop  GS^lfi  assembly  lansuagc  pruRrains  on  the 
GS.  There  arc  four  key  modules: 

■  The  shell  (eommand  interpreter) 

•  The  text  editor 

•  The  linker 

•  The  f)5B16  assemljler 

ByacriuirinR  APW-Loiupatjhle  Loinpikrs,  you  can  also  use  APW  to  develop)  programs 
written  in  higher-level  languages  like  C  and  Pascal. 

To  bcRin  writing  a  fiSHIti  program,  start  up  APW  and  ensure  tKat  the  active 
language  is  658ie  a-s-scndily  by  entering  the  ASM65816  L'Oiuin^nd  from  the  shell, 
(This  lauguas*-  t^"*"  '"'t'^'  deliiult.  you  can  skip  thi.s  step  il  ynu  have  not  switched 
to  another  language.I  Ytju  iiuist  choose  the  correct  language  because  the  assembler 
will  not  deal  with  source  files  created  by  the  editor  when  another  language  is  active. 
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The  next  step  is  to  invoke  the  editor  with  the  conmiiVtid: 

ED[T  pathname 

where  "pathiiaine"  represents  the  name  of  an  existing  snurgq-  file  or  the  name  oi'lht 
new  R!p  >oii  want  to  ereatc. 

Nim  the  liiircl  |)art:  you  must  wrik-*  your  iipplii-atioii!  Tii  dn  this  teijuirei  an 
intimate  kiinwietlfie  iii  the  syntacticul  icqiiireiiients  uf  the  LLssenihlcr. 

Spyrcc  Code  Formut 

Lijics  of  assembly  lun^uai^c  source  (jode  hue  in;ult'  up  of  Four  fields,  separated  tiy 
one  nr  more  spac-ei.  in  the  fnllowing  order: 

■  Label  field  lu^udly  optiona]! 

■  IrtstrufHon  field 
•  Operand  field 

■  Comment  field  (optiuniilj 

The  major  exceptions  are  enmrnent  lines,  which  befiin  with  or  "V  symbols. 

You  ean  put  whatever  you  like  in  these  lines  because  they  Jre  ignored  by  the 
assemblL-r. 

The  Late/  field.  Tlu'  UbcS  field  opikmitlly  eiintains  3  symbolic  label,  u^uiillv  for 
nwkine  n  pubitiun  within  the  prosraiti  to  which  other  parts  of  the  profjram  can 
refer  Labels  can  alsu  he  associated  with  numerit  constants  with  the  EQU  and 
GEQU  assembler  directives  (sec  below). 

A  bbel  must  hej^in  with  an  alpliabelic  eharaeter  (A  to  Z)  or  an  underscore  {  ), 

Subsecjuent  charatters  can  be  iilphabetit  [A  to  Z).  nunu-rif  (0  to  9),  the  tilde  {'],  or 

the  liuderstore  I  ).  The  nia.vimni:n  liMigtli  is  2.55  eharaetcrs.  The  assembler  usually 

ignores  the  ease  of  alphihctic  characters,  but  yiiu  tan  make  it  case-sensitive  with 
the  CASE  ON  directive. 

The  Instruction  Field,  "llie  instruction  fidd  coiitaius  the  65816  instruction  or  an 
assembler  directive.  Directives  are  eammands  to  the  assembler,  not  fiSHlG  instruc- 
tions. They  IcII  the  assembler  to  dn  such  things  as  set  or  clear  internal  status  flaps, 
define  symbol^,  alltxratc  data  stc>ra^c  areas,  save  object  code  to  disk,  and  create 

matTCJS. 

If  the  label  field  contains  an  entr>',  the  instruction  field  must  not  be  blank:  if  no 
instruction  i:^s  waited,  use  llie  A\OP  [assembler  no  operation!  directive.  Unlike 
some  assemblers,  the  fi581(i  assembler  does  not  allow  you  to  define  lines  that  contain 
only  a  label. 
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The  Operand  Field.  Tlif  tiperantl  field  cuntains  tlit^  addressing  iimdf  for  the 
inslriKlir.li  or  a  paraiiirtcr  lor  the  asseinbk'r  chroctive,  It  may  he  blank  if  ihe 
instrnctioM  ur  directive  rp<inires  no  expht-it  upcrand. 

The  CnmmenI  I'ield.  The  tmtiment  field,  which  hcgijis  willi  a  ;  symlxil,  can  contain 
any  t.'xi)lanatorv  tf\t  ynu  like.  Use  il  lu  dacunxent  your  program  cndv. 

Tlie  sciurc-L'  wde  shfll       a  h^iifa]  (iSfilfi  projfrain  lonks;  rinmetllinf;  like  ihis: 


MyPrograrn 
Mac  r  03 . Mac 


;H.arne  of   object   code  file 
iName  of  matro  -file 
;5larl   of  ma  1 r  code  segment 
tit   li^es  CI  oba  1  E>d  tfl  da  ta 
I'-Privflte"  15  a   local  labe! 


nA  globaJ    Entry  point 


iflticther  code  segment 
;lt  can  use  CiDbalData  too! 
;You  can  acctss  through 
;glDbat   entry  pn i r t 9 . 
;Error!!!    But    fiq  t    local  ones, 


;Hqme  of  other   file  to  include 


KEEP 
MCDPY 

CodeS^gl  START 

USING  Global  Data 
Private  NOP 

<put  program  code 

here> 
PlySiib  EMTBY 

<rtiiirp  pro-gram  code 

h  e  r  e 

END 

CodeSegS  START 

USING  GlobalData 
JSR  CodeSegl 
JSR  MyStib 
JSfi  Priuate 
tfcude  for  another 
aegmtnt  he^e^■ 
END 

CDPY  athcrCode.Asm 

iiobelDala  DflTfl 

<put    data  allocation 
statements  here-- 
END 

The  "KEEP  pathiiaiiie"  directivt'  saves  to  disk  the  iihj<'ct  code  geiLeratecl  hy  tjit- 
assefmWcr  inuk-r  itiimt-s  nl"  thr  form  "palhiiaint-  ROOT"  [for  ihL'  fir^t  todi?  'ic^mcnT 
Iti  tilt:  proj^iaiiil  nml  'pathriiunc-  A"  (fur  all  iillicr  st^nm tails,  if  unv  J.  Tlie  ProDOS  file 
lyiK'  code  ibr  lliese  files  is  SBI  ,k|jd  lilt  standard  iimcmoiiic  is  OU).  Tht-  KEEP 
directive-  must  iippt-ar  bdiire  the  firsi  STAU1'  dirL-L'Mvp. 

"VICOPV  pathtirtinc"  Iclls  llic  [iKscTnhk'r  llit  nanii.'  of  thr  file  in  wliich  iiiatids 
referred  In  in  the  source  file  are  dcfiiiKd.  Macros  uill  he  dcscrihpd  in  greater  detail 
below. 

COP^  patfiiiame  U-lls  Ihi*  a-iscmblcr  !t>  luad  the  ^p■ecificcl  suurce  file  and  assem- 
ble its  statcinpnt.s,  On  L'oiiipU'tinn,  assembly  continues  with  the  next  line  in  the 
niai[i  file.  Use  it  lo  incliKk-'  stancljir'c]  source  code  frajimrnts  in  your  UYdiu  soiir^t 
proprtlin  file. 

All  65816  inslriiclioti.s  in  ii  prowrani  soutvc  file  miihl  fall  inside  iillt"  or  more  code 
segments  defined  by  .^TAKT  acid  END  direslivcs.  STAIH'  TiiLirks  the  bl"')^itnlille  oi' a 
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LDile  segment  and  must  be  associaled  with  ii  label  thai  identifies  the  subroutinf  or 
iiiiiii  pnig,ram  in  the  ^PKiiifiil.  KND  marks  tlie  end  ui  ihe  ieKint-nt. 

A  single  stiiii-cv  file  may  contain  ativ  iiuiHbi,-r  ot'ttxle  se«int;iits.  The  advantage 
ofpartiiioninfi  a  pmsriinn  into  several  segineuts  is  tliat  all  lnhe^U  defined  inside  Ehr- 
^eement  lu  l'  \<>cj.]  to  thr  SCRincnt.  This  niCDilS^  ihilt  the  .'lanie  khels  ean  he  reused 
in  anuthi-r  ^t'HiTK-nt  witlioul  H^'nt'Tatiiig  ait  asseiiihU'  emir.  Tliis  i;;  eLspecidly  eiin- 
veiiient  if  you  arc  di'vt-loping  estrcmcly  large  programs  in  whiuh  ihe  risk  of  symhai 
cUipltcntion  is  qreat 

The  lahfl  used  widi  the  START  directive  is  global,  which  means  thai  it  caimol 
be  used  as  a  label  anywhere  else  in  the*  program.  It  identifies  the  primary'  entry 
point  to  the  sulmiutinf  ettnt^iined  in  the  scijmfMit,  You  can  use  the  ENTItY  direttive 
to  define  other  Kldjal  entry  points  into  the  suhroiiliiie,  if  you  wish.  Like  STAliT, 
E\THV  requires  a  label. 

You  can  define  prosriiTyi  sefiments  (hit  enntain  only  data  (tio  instructions)  with 
the  DATA  directive.  A  data  segment  must  end  with  the  END  directive. 

As  yoLJ  might  expect,  the  labels  inside  a  data  segment  are  local  to  that  segment, 
althougli  tlie  name  ol  the  data  segment  is  i^lobal.  You  can.  however,  associate  a  data 
segment  with  u  code  se^;ment  .so  that  the  data  M  gnient's  labels,  in  effect,  become 
local  to  the  tiode  segment  as  well.  To  do  thi.s.  use  the  USING  DataSegName" 
directive,  A  data  segment  may  he  used  hy  any  code  segment  in  this  way. 

Local  and  Global  Labels 

liou  will  probably  want  tn  assneiate  symbolic  khcls  to  numeric  constants  to  make 
your  source  code  easier  tii  understand  and  to  debug.  Vou  can  do  this  with  the  EQU 
(equate)  or  GEQU  [global  equate)  dirccinves. 
Here  are  some  examples: 

True        GEQU         *SOOO  stakes  effect   througliout  pro^gram 

BilPos     EQU  3  jtakeseffectiiicurrert  segment 

GEQU  treates  a  global  constant — one  that  takes  effect  in  every  code  and  data 
Segment  in  the  source  file.  The  same  label  may  not  be  redefined  elsewhere  in  tlie 
prOf^ram. 

EQU  Creates  a  local  constant,  which  takes  eflect  only  inside  the  segment  in  \vhii.'h 
the  constant  was  defined.  EQU  labels  can  be  redefined  in  other  segments.  If"  an 
EQl.'  label  hai  the  same  name  as  a  (iEQU  label,  the  EQU  label  takes  precedence. 

Pi  oDOS  16  Entry  Conditions 

JiLst  hf'fbrc?  ProDOS  16  pixsses  LOntrol  to  an  application,  it  puts  the  system  into  a 
stand;ird  npcrEiting  state: 

*  full  native  mode  {m=0,  .r=0,  e=0) 
■  the  X  and  Y  registers  are  zero 
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■  the  A  register  contains  the  ID  tag  for  the  prnKcam 

•  shacinwing  of  the  text  screen  is  on 

"  shadowing,  of  the  grapliits  area  [s  off 

•  lyo  shadowing  and  languaKt-  uard  operalion  is  on 


(The  concepts  of  ID  tags  and  lihadowing  T.vill  he  explained  in  chapter  4.) 

In  addition,  PrnDOS  16  reserves  a  space  in  hank  SOO  for  use  as  a  direct  pa^e  and 
stack  area.  This  is  normally  a  I K  spaLt,  hi](  can  he  changed  using  advanced  assembly/ 
Unking  lec-hlliques.  On  entrv-  to  tlie  program,  the  diret:t  page  register  cimtains  the 
address  of  the  first  hyte  in  this  space  and  the  slack  pointer  points  to  the  last  byte 
in  the  space. 


Mode  Considerations 

AftPr  ProDOS  16  [(lads  an  executahic  apphcation  into  memory,  it  puts  the  65816 
into  ftill  native  mode  with  I6-hit  A,  X.  and  Y  reglhters;  It  then  passes  control  to  the 
beginning  □!  the  first  uxle  5cgnii  nt  Thi^  means  the  program  docs  not  have  to 
change  modes  with  XCE  or  REP  il' it  needs  to  run  in  hill  native  mode. 

The  assemhler  niust  he  told  of  any  changes  in  the  size  of  the  accumulator  and 
indes  registers  so  that  il  can  assemble  the  following  instructions  fSirrectlv: 


LDA  'immediate 

LDX  ' i  mmed la le 
LDY  ' 1 mmed  ia  te 
ADC  itimmediale 
AMD  *  1 mmed ifl te 


SBC  >immediflte 

EDR  '  1  rnmed  i  a  t  p 
BIT  'immediate 
DRS  i»  1  mmed  IS  t  e 


The  assembler  initially  assumes  settings  of  LONGA  ON  (16~hit  accumulator)  and 
LONGl  ON  (Ifi-hit  index  registers).  LONCA  and  LONG!  are  directives  that  appear 
in  the  instruction  field  of  u  line  of  snnrct-  code.  11  the  directive  is  set  to  OFF,  the 
assemhier  umiiders  the  corresponding  re^ster  to  he  S  bits  in  size. 

Any  time  yiiu  change  register  sizes  using  REP  or  SEP,  you  must  also  tell  the 
assembler  by  adjusting  LONGA  and  LONCI  to  the  appropriate  values. 


Numbering  Systems 

The  APW  assembler  nndqrstantl*  many  different  numbering  systems.  The  ones  you 
will  use  most  often  arc  tk'tirnal,  liexadpcimal,  Lind  binar\-.  To  indicate  which  .system 
you  are  using,  place  a  special  idenlificaliou  character  in  frunt  of  the  number; 
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$      ileSiideLiiTial  number  (for  example.  *KFAD) 
%      Biiian.'  numlier  [for  nsamplr.  9f.flilU0JU} 

No  si>cua[  fhiirdt  ter  is  needed  iur  a.  decimal  number,  beciause  dt^dmal  is  iKl'  defauli 
numbcnng  system. 

Isolating  tht;  Wurd^  in  a  l--t>iig  Address 

You  pitfii  nted  tu  Ujnd  n  rc'jU;i.stCT  with  the  low-  iir  hif^ln-ordcr  wnrd  iif  a  piirtit-'idiir 
address.  Luadiii;>  th<"  low-order  [nirtitiii  in  easy: 

iDft  JAddress  iLoad  addreaa  (low) 

Because  the  A  register  (or  X,  Y)  lf>  bils  in  size,  ihe  upper  H  bits  of  Address  are 
igtiured.  To  ii>ad  tbe  liiRh-OTdL-r  purtiuii,  you  must  append  "\-lfi"  to  tlie  iiddre^s 
operand  i(wbie!L  me^ins  '"sbil't  right  by  Ifi  hits")  nr  precede  it  with  as  shown  in 
the  lolluwiiij;  e.xitmples; 

LDfl  •flddrBss|-1S         iLcad  high -order  word 

LDfl  fflddress  ;  [  a  1  tsr  nat  i  ve  mitthod) 

III  botli  ea^eh,  the  bank  portion  ihe  24-bit  addies-s  is  [be  biw-order  8  bits  of  the 
aeeuiuulatur.  Thi-  tap  H  bits  are  zero. 

For  PEA  operations,  do  not  imchide  ttit-  "#"  because  tbe  addressing  mode  i:^ 
absolute,  uat  inimcdiate.  To  push  the  two  words  of  an  address  nn  the  stack,  do  this: 

PEA  flddre55|-16        jPush  address  titgh 

PE:A  Addrea  a  jPu'sh  address  loui 

(The  Al'W  assembler  does  not  alluw  an  "Address  opemnd  fnr  PEA  instructions.) 
This  is  thf  preierred  techntf|ue  for  pushinji  ackbesi  |jointer.H  because  it  doe*i  not 
require  usinj;  a  (iSHKi  rrgi'sfcr- 

Forcing  Addressing  Modes 

When  you  ^ptcily  an  addre.vs  as  <iperiind.  tlie  APW  ^ssembk-r  normally  crinsiders 
it  to  he  an  absolute  udtlri-ss,  as  opposed  to  a  hjiin  absolute  ur  direct  pajtc  address, 
and  assembk-s  the  iTistruction  nct-ordingly.  Exceptions  are  symbuhc  addresses  de- 
fined by  Ei)\.'  (ir  (;E(,)L'  dirrctive-S;  here.  APW  is  able  ta  determine  the  appropriate 
addressiii)^  iiiiide. 

Using  absolute  addresses  may  or  may  not  be  appropriate,  dqiPTidmn:  on  the  state 
of  the  dutu  hank  register.  Ef  tlie  s>  mhnl  lor  the  address  idenliHe.s  a  location  insidi- 
tho  proRir^jn  itself,  ahsiibtte  uddn  ssini^  is  iniproper  if  tbe  data  bank  re^i.stiT  is  nut 
the  same  as  the  prui^rain  bank  le^ister   In  this  situation  you  ean  either  make  tin" 
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two  banks  the  saint'  (with  PIlK,  PLB  instruLMons)  or  furrr  alisohite  long  addressing 
by  prcffdiiig  the  lutnu-  oi'  llif  address  liibel  with  the  >  symbnl. 

Fyr  CKample,  to  load  the  A  rt-fiister  with  wliatevf  r  is  stored  at  !VlyAd(lri?ss,  execute 
the  MIowidg  codf: 

LDH  }M}rLabel  ;Ug«  fib^alule    long  ^ddreasing 

This  lorcts  the  65*iJ6  to  rcatl  the  vulm-  frfim  tht*  program  hunk  as  inttuded. 

Similiirly,  yini  tan  fnrL'c  direLl  paffe  addressing  with  the  "<  '  symbol  and  absolutf? 
addressitij^  uitb  iht-  "\"  symbnl; 

LDfl  -cnyfiddrE55  jForcfi  direct  pag*  addressing 

LDfl  jMyflddress  ;FDrcp  ahsaljle  ^ddres^jTig 

You  would  use  these  only  if  the  assembler  wnuld  normally  assfinble  these  instruc- 
tions usin^  a  different  addre&sin^  mode. 

Data  Ailocation  Direttiveji 

You  will  use  data  alltxratinn  directives  to  reserve  space  for  data  inside  tlie  prugram, 
nr  for  storing  spcLific  values  inside  the  program.  To  reserve  spat*,  use  the  DS 
di  recti  vci 

DS  ;fie5erve  15  bytes 

The  operand  of  the  directive  is  the  number  of  bytes  to  reserve.  The  hne  containing 
a  DS  dirt'ctivf'  may  contain  a  label. 

To  store  spttific  values  in  the  object  code,  use  the  DC  (define  cnnstaiiF)  dirwtive 
insLeiid  of  DS.  It  is  of  the  form: 

label  DC  conalant_de-f 

where  toiistant^def  defines  tlie  type  duta  l:u  bo-  stcircd-  Hrre  sire  examples  of  the 
most  common  constant  definitions^ 

ir22'  One  byte 

12  396'  Two  bytes  (one  word) 

1298  Two  byft's  jono  word) 

l4"-'S8l)(}U"  Four  bytes  [long  word) 

H'h'El'IHA'  Hesadpciinal  digits 

B'KHtllO'  Binurv  digils 

C'Te.tl  Strin;^'       Sefjiicncc  of  characters 

The  Ii  di-fiTiition  [.t  is  an  intctijcr  from  1  to  H),  storc-s  multiple  bytes  in  memory,  low- 
ordei  bytes  hrs!.  This  is  the  ordt-r  expected  by  fiSfSie  instructions.  If  .v  is  omitted. 
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two-liytf*  words  iire  stored.  The  number  specified  can  be  in  binary.  dcciinaL  or 
htfxiidtcinia]  iorin. 

The  H  dcfiiiitiijii  iturfs  successive  pairs  of  hcxadcdinal  digits  in  successive  mem- 
Qr>'  bytes.  (Any  spaces  in  the  digit  sErinj^  are  i(riiore[I.  J  U'an  odd  number  of  digits  is 
specified,  tht^  low-urder  four  bits  of  ttie  East  hytn  will  he  set  to  0, 

TKl-  B  dtfiuitioti  stures  successive  sruups  c>f  ei^lit  binari,'  dij^its  iii  successive 
iiieinun,  bytes,  i^iiurinj^  any  spaces,  If  the  number  of  dislts  specified  is  not  an  even 
niLikipIe  nf  eight,  the  last  byte  is  padded  an  the  riijbt  with  l>  bits. 

The  C  definition  stures.  the  ASCII  I  codes  lor  the  speLsfifd  charat  ter  striuE  in 
memory.  The  MSB  ON  and  MSB  OFF  direetives  mntml  the  setting  of  the  high  bit 
for  these  string  constants.  The  di?fuJt  is  MSB  OFF,  meaning  that  bit  7  ofpach  Iwte 
is  0.  Use  MSB  ON  ii'  vtju  m  i.sh  to  Itircf  bit  7  to  L 

St^veral  constant  deJinition^  can  he  included  on  one  line  by  separating  them  with 
cominas,  For  ("iainple,  the  cummJind; 

DC      1 1  '  0  '  ,  12  f  JFDDfl "  ,H  '  BE ' 

stores  the  li.yte.'i  m>  SDA  ^FD  *AE  in  the  olyect  code  at  as.^emhly  time. 

To  define  several  items  of  the  same  general  type,  put  the  items,  separated  hy 
commas,  iiiiide  the  single  quote  marks  of  the  tOdStant  definition  string: 

DC      I2'34,tA32l  ,16'      iStorsd  az  22   DD  21    A3   10  00 

Another  nice  feature  nf  the  DC  directive  is  that  it  gives  you  the  ability  to  put  a 
repeat  t'nunt  in  front  of  a  constant  definition.  For  example,  to  generate  i\\  c-upies 
ofSP  UEn.  use  tile  iollowint!  cpmmand; 

DC  GPiFDED' 

Notice  thiit  in  this  cxaiiiple  the  "2 '  aFtt-r  the  T"  was  omitted.  As  indicated  above, 
th^  assembler  ^.ssunuvs  it  is  dealing  with  words  in  this  situation. 

Listing  Direcdves 

The  APVV  assembler  siipports  several  directives  that  aflPect  the  output  of  the  assenddy 
process: 


«  LIST  (display  object  cude] 

•  SYMBOL  {display  symbol  table) 

•  ABSADDR  (display  codt-  addresses) 
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«  INSTIMIil  (display  instructinii  cydi?  times) 
•  GEN     [display  inatro  cxpansionst 

These  dir..tiv..       .ilh.r  be  ON  or  OFF;  put  th.  ON/OFF  status  indicator  in  the 
operand  field  The  defaults  for  all  thesp  directives  is  OFF. 

Creating  the  Macro  File 

,  niacrn  is  as....blcr  comnwd  that  expands  int.  .  scries  of  65816  instruction, 
t:  Lbler  directive.]  dunn.  the  ..en.bly  prc.es.  By  ..si.n.n.  c.mn.,nly  n.ed 
short  code  IrafLmonts  U,  a  ....rn  command,  you  can  develop  program,  much  u.ore 
rapidlv  ^o(l  make  them  .nueh  more  rcadahk-  at  the  .ame  time. 

the  next  ehapter  will  di.enss.  the  .oppnrls  ,n.ny  too  set  (^^-t--;^^^^^^^^^^^^ 
invoke  bv  Inad-u^  th.  X  re^i.ter  with  .n  ID  nomber  .ncl  then  d.nig  a  JSL  to 
^^m:  Vou  do  .ot  h.ve  to  mc..on.e  thes.  ID  number.,  ^^--^  ^pple  prov^  ^ 
^.-ith  APW  a  set  ..f  macTO  definitions  that  associates  easy-tn-r^member  nam*.  ...th 
each  of  the  LDX/JSL  fuactioit  calls. 

Ynu  can  deh.e  powerlul  n.aeros  for  use  ^Wth  the  APW  assemb  .r.  For  a  eompre- 
hens.ve  de.cr  p  ion  of  ho-  to  create  -r-aeros,  see  the  AF^V  A..a,>b^  Reference.  To 
'"a  fe.l  for  how  to  .reatc  macros.  K^^k  at  this  o..,  c.lk-d  l'u.hAddr.  wbeh  poshe. 
the  luidress  of  a  proiinim  or  data  area  on  tlw  stacks 


MACRO   ■  ,  E 

Slab         PushAddr  Saddr  :Nam.  of  macro,  param.ter^ 

Hat,         PEfl  Iaddr|-16  ;Body  of  macro 

PEA  *addr  -.Body   0+  macro 

MEHD  ■  ^'"^  macro 

To  invoke  thi^  n>acro.  vou  would  place  a  line  such  as: 
MyLobel  PustiAddr  MyRtcord 

i„  vour  pn.sram  source  c^de.  When  th.  assembler  expands  the  macro  into  65B16 
i^s  Z^ions  it  reph.es  &lab  with  MyLabel  and  &addr  ^-ith  MyR«..rd  wherever 
t'erapp"  r  in  the  hndy  nf  th.  macro  dcHnitlon.  For  the  above  e^.npic,  th.s  mean, 
the  following  statemcnt^  woold  he  Kenerated: 

MyLabel   PER  MyRpcordrlS 
PEfl  Plyfiecord 

The-  MACHO  directive  m^ks  the  beginning  of  th^-  macro  definitLOT,   The  next  line 
Lnt^n.  the  name  nf  the  .aero  in  the  in.trucHoo  field.  It  -^o  dehnes 
vm.  can  DBS.  to  the  macro;  their  ntimcs  besin  with  tht-  tf  symbol.  For  1  usliAddr. 
o  c  pir.X    s  a  l.bcl  .ppearin.  in  the  label  field  (^bb);  the  other  is  an  address 
apprrln^X  ^Per-d  T-'d  (bcaddr).  Multiple  oonl.bel  parameters  appear  m  tl,e 


;  St  art  macro  def  knl t ion 
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operand  field  of  a  macru^  separated  by  commas.  The  MEND  diretrtive  marks  the 
End  of  llie  inac:r(9  definition. 

With  L'onditional  aistfinbly  lEfL-hnique!>  you  cai]  define  macros  whose  behavior 
depends  on  many  things,  suth  as  whether  the  parameters  you  speeifj,'  are  immediate 
values  Or  addresj^ey.  Examples  of  macrus  lilte  this  are  given  i"  listing  2-1.  (These 
macros  are  ided  I'or  pasiinf-  paramieters  to  toul  set  functions  and  tor  retrieving: 
results,  as  will  be  shown  in  the  next  chapter.)  Consult  the  AFW  AssembSer  Reference 
for  a  detailed  explanation  of  how  tn  use  ihcsc  advanced  macro  features, 

Almost  every  program  you  write  for  the  CS  will  use  macros,  primarily  the  ones 
that  assign  symbolic  n^imes  to  tool  set  fmictions.  The  macros  must  appear  in  a 
separate  file  that  is  referred  lo  by  an  "MCOPY  pathname"  directive  in  the  primary 
source  code  file. 

APW  comes  with  a  program  called  MACGEN  that  you  can  use  to  extract  the 
macros  needed  by  a  program  from  the  standard  APW  macro  files  and  tn  put  thrm 
in  a  custom  macro  file.  For  example,  snppose  your  source  program  is  called  WIN- 
DOWS.ASM  arid  it  uses  macros  dcESned  in  MJ6. QUICKDRAW  and 
Mlfi, WINDOW.  To  place  all  tfie  macros  used  by  the  program  iii  a  file  called 
WINDOWS.  MAC  (the  file  named  in  the  program's  MCOPY  command),  type  in 
this  commaTid; 

MACGEN  UlNDDbJS.ASM  L-JINDQtJS  .MAC  til  £ .  QU  I CXDS  Ahi  MIB.UlNDakg 

MACGEN  scans  the  source  file  (the  first  file  named)  for  maeni  references  and  places 
their  definitinns  in  the  maLTO  file  [the  seennd  file  named).  It  searches  the  thirtl  and 
fourth  files  [and  any  more  y<]u  mijjlit  specify  on  the  cnnimand  line)  for  these  macro 
definitions.  If  not  ail  macros  are  found.  MACCEN  asks  you  to  enter  the  name  of 
another  macro  file  to  Jiearch;  it  keeps  asking  until  it  findti  every  definition. 

Quite  often  you  will  create  a  macro  file,  tlien  change  the  program  slightly  so  that 
it  uses  a  few  new  macros.  add  jusl  tlie  new  macros  to  tlie  existing  program  macro 
file,  spetify  the  program  macro  file  ai  one  of  llie  MACGEN  search  files: 

MflCGEN  WINDOWS. ASM  WJNDDWS.MAC  WINDOWS. WflC  MIE.WIHDaW 

By  dujn(;  this,  vnu  avoid  havin;H;  tri  specify'  the  names  of  all  the  svstem  macro  files 
containing  the  macros  you  already  h;ive  in  the  program  macro  file. 

Creating  an  Applccation  with  APW 

The  APW  lisscmblcr  processes  a  65816  source  code  file  and  L'Onverts  it  into  an 
object  code  file.  The  resultant  object  code  file  is  not  the  executable  program, 
however.  Instead,  it  contains  code  mudules  tlial  the  AFVV  linker  must  process  first, 
It  is  the  linker  that  creates  the  executable  ProDOS  16  Load  file.  A  load  file  contains 
the  program  code  and  a  header  that  tells  the  System  Loader  (the  tool  set  responsible 
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for  loading  programa  into  memory)  how  tn  make  the  program  nin  properly  at  llie 
load  address - 

Object  code  Rlcs  produced  by  the  assembler  are  in  a  sped&l  knf^uaf^e-iiidepen- 
dd-nt  format  defined  by  Apple,  ilisli-lfvcl  language  L-oinpilers-  th^it  work  in  the  APW 
enVLroiiinent  [notahly  C  and  Pascal)  use  this  saiuL-  fonnat-  The  linker  dues  not  cure 
whit'h  language  crcattrd  the  object  code,  so  you  can  develop  portions  of  a  program 
in  dilierent  faIlgua^;e^,  then  combine  thDin  with  the  linker  to  create  the  final  appli- 
cation- 

Tlie  APW  TOmmanci  for  asseinhling  and  linking  simple  applieations  in  one  step 
is  ASML-  Ifyoii  ne*?d  to  perform  special  MnkinR  operations  [sut-h  as  intludinfr  code 
libraries),  you  have  to  separately  pracf  s-,  a  Unker  control  file  written  in  the  LINKED 
language  instead:  fur  information  on  the  LINKED  language,  aec  the  APW  Assembler 
Reference. 

After  asscmblinfi  and  linking.  APW  creates  an  ejceciitable  ProDOS  16  load  file 
with  a  file  type  code  of  SB5  (the  standard  mnemonic  is  EXE).  Tliis  program  can  be 
run  from  the  APW  shell  simply  by  typing  in  its  name  When  it  ends  (with  an  RTL 
instruction  or  a  ProDOS  16  QUIT  commaiidl.  control  rctumi  tn  ike  shell- 
Once  you  have  thoroughly  debused  the  program,  you  should  change  its  file 
type  code  to  SB3  (the  mnemonic  is  S16)  so  that  ProDOS  16  will  recognize  it  as  an 
apphcatiim.  Do  this  with  rhe  APW  FILET^'PE  command: 

FILETVPE  pattiname  %B3 

where  SB3  is  the  new  file  type  code,  Yon  can  specify  the  S16  mnemonic  instead  of 
ttie  henadeciinal  code,  if  you  wisli. 

An  S16  program  can  be  executed  from  the  APW  shell,  hut  it  will  crash  the  system 
if  it  ends  with  an  RTL  instruction.  This  i^  because  the  shell  removes  itself  from  the 
system  when  it  pa^ises  euntrol  to  the  program,  so  it  will  not  be  there  on  return. 
(With  EXE  programs  the  shell  stays  intact.)  llie  moral  is  Co  always  end  a  program 
wtth  a  ProDOS  QUIT  command.  This  command  is  described  in  chapter  10. 

REFERENCE  SECTION 

Table  K2-1;    The  C:ompIete  658 16  Instmction  Set  

Effect  on  Fiags 
Atldressing  NV-BDiZC  fl=I 

Moth'  Cycles    NVm?:DlZC  c=0 

#immediatc  2'  HV,  ,  .  .ZC 

addr  4^ 

long  5' 

dp  3' 


InstrurHon 
Mnt'vionic    Openttiim  Opcodt 

ADC  add  lo  accumnlatwr  $69 

v.'ith  carry 

36F 
$65 
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Itixtruclion 
Mnemonic  Operation 


EffrrA  tm  Fla^s 
NV-RDIZC  e  =  l 


AND  Ui^K'dl  AND  Willi 

ac'LUmulakir 


Made 

Cijd 

$71 

(dp).Y 

_  1  3 

«77 

[dpl.Y 

6^ 

$61 

(dp,X) 

6' 

$75 

dp.X 

4' 

S7D 

addr,X 

S7F 

long.X 

5' 

$79 

addr,Y 

572 

idp) 

5' 

S67 

[dp] 

6' 

S63 

sr.S 

4' 

573 

lsr.S),Y 

7' 

S29 

#iinnicdiatp 

2' 

$2D 

addr 

4' 

S2F 

long 

5' 

$35 

dp 

3' 

$31 

(dpKY 

$37 

[dp|,Y 

m 

(dp,X] 

6' 

dp,X 

4' 

$3D 

addr.X 

$3F 

long.X 

5^ 

$39 

addr.Y 

4" 

$32 

(dp.) 

&' 

$27 

[dp] 

6^ 
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Effect  on  Flags 


Imimctuin 

Addres^rifi 

NV-BDIZC  p-1 

Mnemonic 

Operation 

Opcodc 

Mode 

Cycles 

NVmxDIZC  e^O 

sr,  S 

$33 

(sr,S).Y 

7 

ASL 

arithmetic  shift  left 

SOE 
$06 
90A 
$16 
$1E 

addr 

dp 

A 

dp,X 
addr.X 

6^ 
5* 
2 

6^ 

N  ZC 

BCC 

branch  on  carry 

$90 

rcl 

clear  (0=0) 

BCS 

limiich  nn  cam'  set 

$B0 

24.= 

[C-lJ 

BEQ 

branch  <jn  equn] 

iz-i) 

SFO 

re] 

»     t     t  m 

BIT 

Logically  AND  the 

!589 

#im  mediate 

2' 

NV. . , -Z. 

acciiiniilator  wiih 
ihv  operand; 

S2C 

iiddr 

4' 

transfer  high-order 

S24 

dp 

3' 

hits  to  N  and  V 
(hiit  not  if 

S34 

dp,X 

4' 

#ini  mediate} 

83C 

addr.X 

BM[ 

braiK'b  on  minus 

$30 

rt-l 

(N-li 

BNE 

brunch  *in  nut 

$D0 

rH 

eqnul 

[Z=0> 

BPL 

branc]i  on  p]us 
(N=0) 

$10 

rel 

2*  = 
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Effect  an  Flails 

Instruction 

Addrpssing 

NV-BDiZC  F=l 

Mnemonic 

OperatUm 

Opcode 

Mode 

NVmxDIZC 

BRA 

htatith  relative 

$80 

rel 

3' 

always 

BRK' 

break  iutemipt 

$00 

{stack} 

....  01  .  . 

BRL 

braneh  relative 

$52 

longrel 

4 

long 

BVC 

bmnth  Qii  overfluvv 

$30 

rel 

clear 

BVS 

branch  on  uverflijw 

$70 

rel 

set  (V  — ij 

CLC 

clear  carry  flag 

SIS 

(implied} 

2 

- — ■  

 0 

CLD 

clear  dei,-imal  Aag 

(implied} 

2 

........ 

CLI 

SDH 

{implied} 

2 

 0  .  . 

flag 

VjLjV 

cl-ear  overflow  flag 

ID- 13  11 

j  implied} 

2 

CMP 

comparif  will) 

SC9 

#  immediate 

2" 

N  ZC 

accumulator 

SCD 

addr 

4' 

3CF 

long 

5^ 

$C5 

dp 

3' 

$D1 

(dp),Y 

$D7 

[dp],Y 

& 

$C1 

(dp.X) 

6' 

$D5 

dp.X 

4' 

$DD 

addr.X 

3DF 

5' 

Reference  Sectiuu  S3 


Effect  on  Flags 


Itistniction 

Addressing 

NV-BDIZC  e=l 

M  nemunic 

Operation 

Opcode 

Mode 

Cyctes 

NVmxDlZC  e=0 

$D9 

addr.Y 

.  1  3 

Iff  J_V  ^ 

5' 

[dp] 

6' 

$C3 

sr,S 

4' 

$D3 

(sr.S),Y 

7^ 

COP 

co-processor 

$02 

■{stack)^ 

7^ 

.  01  . . 

interrupt 

CPX 

tunipire  with  X 

SEU 

#  immediate 

2" 

. . .  zc 

SEC 

addr 

a'' 

SE4 

dp 

cpy 

compare  with  Y 

#  immediate 

2" 

N.  , 

. .  zc 

*cc 

addr 

dp 

i 

DEC 

decrement 

SCE 

addr 

6= 

N  .  . 

.  .z. 

see 

dp 

S= 

«3A 

A 

2 

SD6 

dp.X 

a' 

SDE 

addr.X 

DEX 

decrement  X 

$CA 

(implied} 

2 

M 

z. 

DEV 

decrement  V 

S8S 

(implied} 

2 

N 

z. 

EOR 

rvc'lusivf  OR  with 

S49 

#  immediate 

2' 

M  .  . 

2. 

attunjulator 

S4D 

addr 

4^ 

$4F 

long 

5^ 
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Effect  tm  I'lags 


Inslruciion 

Addressing 

NV-BDJZC  t=  1 

Mnenumic  Operation 

Opcode 

NVinxDIZC  e=0 

$45 

dp 

$51 

(dp}.Y 

957 

IdpJ.Y 

A  J  1 

(dp.X) 

6 

$ss 

dp,X 

4' 

addr.X 

$5F 

5' 

$59 

addr,¥ 

$52 

[dp] 

5' 

m 

[dp] 

6' 

sr,S 

4' 

$53 

(sr.SJ.Y 

7' 

INC  increment 

SEE 

sddr 

6- 

N .  .  Z 

SEB 

do 

5' 

$1A 

A 

2 

9F6 

dp.X 

$FE 

addr.X 

INX             incrvment  X 

$E8 

{implied) 

2 

N  Z, 

INY            increment  Y 

$CS 

{implied} 

2 

N  Z. 

JMP  jump 

|4C 

sddr 

3 

$6C 

[addr) 

5 

$7C 

(addr.X) 

6 

fle/i'rejice  Section  55 


Effect  on  Fla^s 

Instruction 

Adflmssin^ 

NV-BDIZC 

Mnemonic  Operation 

Vpcoae 

Moae 

JML           jump  long 

*5C 

1cm  B 

4   

$DC 

6   ,  . 

JSL            jump  to  long 

^21 

long 

subroutine 

JSR             jump  tu  i»ubrDUtine 

$20 

J  1 

addr 

SFC 

{addr.X) 

8 

LDA           Iciiid  the 

$A9 

#imiTit:diate 

2'          N  .  -  ,  .  .Z, 

accumulator 

SAD 

iiddr 

4' 

$AF 

lun{; 

5' 

$A5 

dp 

3' 

$B1 

(dp).Y 

$B7 

[dp].Y 

6' 

%A\ 

(dp,X) 

6' 

$B5 

dp,X 

5' 

SBD 

5 

SBF 

Jong,X 

G 

SB9 

addr.Y 

1  1 

$82 

(dp) 

5' 

$A7 

[dp] 

6' 

SA3 

4' 

$B3 

n  1 

i 

LDX           load  the  X  rt^gistcr 

$A2 

#  immediate 

2 '         N .....  2 . 

liAE 

iiddr 

4' 

5A6 

dp 

3^ 
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Effect  an  Fta^m 


Inntmction 

NV-BDIZC  ^-^l 

Mitemonic  OpcratUm 

Mode 

Cycles 

NVrnxDIZC  e=0 

dp.Y 

4~ 

adtlr.Y 

.7  3- 

LDY           load  the  V  register 

SAO 

#1111111  ediate 

2' 

K.  .  . 

Z. 

SAC 

uddi 

4" 

3iA4 

dp 

3" 

SB4 

dji.X 

4' 

SBC 

3(ldr,X 

LSR            liigiuid  sliift  ri^ht 

$4E 

dddr 

0 

zc 

SIR 

$4A 

A 

2 

$56 

1 

ap,\ 

6 

S5h, 

:id(ir,.\ 

MV'N           move  block 

$54 

src.dest 

r 

l^mrkw  iird 

 -_  — 

MVP           move  block 

$44 

7" 

>    ■    <   «  « 

forward 

NOP           mi  operation 

SEA 

{implied! 

2 

ORA           lofiLcal  OR  willi 

S09 

#imniediate 

2' 

N 

z. 

accum  iildtor 

SOL> 

addr 

4' 

$(;f 

Ions 

-1 

73 

.S05 

dp 

3' 

Sll 

(dp).Y 

$17 

[dp].Y 

6^ 

SOI 

((ip.X) 

6' 

Ueference  Section  57 


Mneittcinic 

instniciKfii 
Operation 

Opcode 

Aaarisssin}!, 
Mode 

Effect  an  Flat^n 
NV-BDIZC  e=l 
Cycles   N'VmxDlZC  f  =  0 

S15 

dp.X 

4' 

ISID 

adilr.X 

$1F 

5^ 

$19 

addr,Y 

$12 

(dp) 

5' 

$07 

[dp] 

6^ 

$03 

sr,S 

4' 

$13 

(sr,S),¥ 

—1 

1 

PEA 

pusFi  efFettive 
address 

SF4 

(iddr 

5   

PEl 

push  effective 
address  indirfcL 

$D4 

(dp) 

6   

PER 

push  eHet'tivf 
address  relative 

$62 

rel 

PHA 

push  the 
accumulator 

$48 

{stack  ^ 

3 

PHB 

push  data  bank 
register 

$8B 

{stack} 

PHD 

push  diretl  page 
re^ster 

lOB 

{stack} 

4  

PHK 

push  prugraai  bank 
register 

S4B 

{slack} 

PHP 

push  status 
register 

m 

{stack} 

PHX 

push  the  X  register 

5DA 

{stack} 

3'   

Programming  the  65S16  Micnipracesfior 


Effect  07i  F/ags 


Instruction 

Addressing 

NV-BDIZC  e-1 

Mnemonic 

Operation 

Opcode 

Mode 

Cycles 

NVmjiDiZC  e=0 

PHY 

push  the  Y  register 

S.5A 

{stackj- 

3' 

PLA 

pull  tilt 

S6S 

{stack} 

4' 

N  Z. 

accumulator 

PLB 

p\ill  (l-Jta.  IidnJv 

{stackl 

4 

N  Z. 

rcj^  stEr 

PLD 

pull  direct  page 

{stack} 

5 

H  Z. 

PLP 

pu]l  status  register 

S28 

{stack} 

4 

HVrnxDIZC 

PiJK. 

pul!  the  X  reRister 

IBFA 

{sCacky 

4' 

N  Z. 

PLY 

puU  the  Y  register 

$7A 

{stack} 

4' 

N  Z. 

REP 

reset  status  bits 

$C2 

ff  immediate 

3 

NVmxDI ZC 

ROL 

rotate  left 

$2E 

addr 

6= 

N  ZC 

$26 

dp 

S» 

«2A 

A 

2 

$36 

dp,X 

6= 

S3E 

addr,  X 

/ 

ROE 

rotate  right 

$6E 

addr 

6= 

N  ZC 

$66 

dp 

S6A 

A 

a 

S76 

dp.X 

J7E 

addr.X 

7^ 

RTI 

return  from 

$40 

{stack) 

NVmxDIZC 

inU'rriipt 


Reference  Section  ^9 


Effect  on  fUt^s 

Instruction 

Addressing, 

NV-BDIZC  e'=l 

Mnemonic 

Operation 

Opcode 

Mode 

Cycles 

NVinxDIZC  e=0 

RTl 

rt-iiiru  rrom 

e 
D 

sTibroutme 

long 

RTS 

return  from 

$60 

{stack}  . 

G 

subroutine 

SBC 

subtract  from 

$£9 

#  immediate 

2' 

NV. . . .ZC 

accumulator  with 

$ED 

addr 

4' 

$EF 

long 

5^ 

$E5 

dp 

3' 

3F1 

(dpj.Y 

5'-" 

9F7 

IttpJ.Y 

6' 

SEII 

(dp,X) 

6' 

SF5 

dp.X 

4' 

Sr  D 

afldr.A 

4 

%¥¥ 

long.X 

5' 

tF9 

addr.Y 

{Op} 

e1 

o 

$E7 

6^ 

iE3 

sr.S 

4^ 

IF3 

(Br,S).Y 

7' 

SEC 

set  cariy  flag 

S38 

{implied! 

2 

 1 

SED 

set  decimal  Ha^ 

$FS 

{implied} 

2 

.  .  .  .  1  .  .  . 

SEI 

set  IRQ  disable 

$76 

{implied} 

2 

 1  ,  , 

flag 
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Efft'tA  fiw  Finns 

!nstnictiar}  Addrcsjtine  W-hDlZV,  c=  1 

Mnemonic   Ofieraiion   Opcode    Mode  Cijtles   >JVni>DIZC  c'  =  0 

SEf  set  status  bils  $E2        #inimediatc   3  MVmxDIZC 


STA 

store  the 

S8D 

iiddr 

4"   

accumulator 

long 

5= 

$85 

dp 

3' 

$91 

Idol  ¥ 

$97 

|tlp],V 

6' 

$81 

[dp.X) 

6' 

$9.5 

dp,X 

4' 

$9D 

addr.X 

$9F 
$99 

king.X 

addr,Y 

.5' 

5" 

$92 

(dp) 

5' 

$87 

[dpj 

6' 

$S3 

sr,S 

4' 

$9,3 

(sr.SJ.y 

7' 

STP 

stop  the  prcx^essur 

$DB 

{iniplii'd} 

3   

STX 

store  the  X 

$dE 

addr 

4'   

register 

$86 

dp 

3" 

$96 

dp,Y 

4' 

STY 

store  the  V  register 

$ac 

addr 

$84 

dp 

3' 

194 

dp.X 

4' 

Reference  Section  61 


Effect  im  Flasis 


Mnemimic 

InstructUm 
Ofieratitm 

Opcode 

AtltlrcMsinfl 

NV-BDI'ZC  f=l 

STZ 

slorr  xt^TO 

59C 
364 
$74 

$9E 

ad*lr 
dp 
dp.X 
atSdr.X 

3 

4' 

5' 

TAX 

transfer  A  lo  X 

&AA 

{implit^d} 

2 

N 

TA^" 

transfer  A  to  ¥ 

$A8 

{implied} 

'2 

u 

n  «  b  . 

■  ■  ^  ■ 

TCD 

transfer  C  In  D 

S5B 

(implied) 

2 

N  .  .  . 

.  -Z. 

TCS 

transfer  C  to  stack 
pointer 

SIB 

{implitfd) 

•1 

TDC 

transfer  U  hi  C 

jiniplird} 

2 

H.  .  . 

z. 

TRB 

tt'st  and  reset  bits 

$i(: 

$14 

addr 
dp 

.  .  .  . 

z. 

TSB 

t^st  and  set  bits 

soc 

$04 

addr 
dp 

6^ 
5^ 

z 

TSC 

transfer  stat-k 

poi  liter  tn  C 

$3B 

{implied} 

2 

N.  .  . 

.  .z. 

TSX 

trjiisftT  stack 
piiintcr  III  \ 

SBA 

{iinplieil[ 

2 

N.  .  . 

.  .2, 

TXA 

transfer  X  to  A 

$8A 

{implied} 

2 

N 

2. 

TXS 

triinsfer  X  tn  ^tm  k 
painter 

$9A 

liniiplicd! 

2 

TXY 

transfer  \  tct  V 

{imjiliedj 

2 

N 

,  .2. 
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Efje£t  on  Flaf^a 


Mnenumic 

Instruction 
Ofiertifion 

Opcode 

Addressing 
Mode 

CydPa 

NV-BDIZC  c^l 
NViiixDIZC(-  =  0 

TYA 

transfer  Y  lo  A 

m 

{iiiiplicdj- 

2 

H  Z. 

transfer  V  to  X 

$BB 

{implied} 

2 

H  Z. 

WAI 

wait  for  interrupt 

■SCB 

■[iniplif'tl}- 

2 

WDM 

{reserved  optxDde} 

342 

{implied} 

2 

XBA 

exchange  B  and  A 

SEB 

{implied} 

3 

N  Z. 

xce' 

^.^\C-■ha^Ec'  carrt  dnd 

?FB 

{implied} 

2 

 C 

^mul:itii)ii  status 
bits 


Notes  on  Cycij:  Times. 

Fur  nil  in.struL-tion5  invuKiiii^  ilin  I'l  pJiRf.  ntliJ  I  cyrlt'  if  hlic  Imv-tircler  Wlc  of  the  diiect  pujle  r4?(£iStL'r  is 

'  Add  I  cydo  irm-O.  ^  Add  1  cvtle  if  c=  I  and  (hi.*  Iiranch  ik  uki-ii 

*  Add  £  L-yt-Jt^s  irin=0.  acron^  d  puRe  bK;iindnn' 

^  Add  1  tydi'  if  in'k'Kine  -lUTosi  »  lunk  tmLiiidary.  Add  I  tyde  iFf^il 

'  Add  I  t^'tlf  if  thL-  lirfiiKh  i'  uIii-ti.  '  Add  1  cvde  if  i={l 

^  7  rycles  per  Lytl"  nlilVi'd. 


Other  Notes: 

]r  the  "Effect  on  Flaes '  column,  i  racttrs  ihv  flae  is  alwiysi  sel.  0  rneuns  ihe  flag  is  idways  denn-d.  and 
a  letter  meuns  that  !he  fiaj;  c-bLini;i'^  rlr'|ifii<lirip  iin  lite  rcsiill  nf  the  iipfnilinn 

'  111  emuLjlLEiii  Hindi',  tlie  B  hit  ii  ^et  tn  1  aft«fr  a  *  XCE  jlwn  aJli'ilS  iht:  Stall  iif  ihi'  dap, 

BRIl  in^lriiL'tion. 
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Listing  2-1:     Useful  Mat-TOs  fur  Program  Development 


;  PushUlord  Vaikje 

i  PushWord  'Value 

;  This  macFo  pushes  a  word  on  the  stack,    ff  an 

;  addre?5   is  specif  ltd  i"V^luc"]>   tNia  i^.  done  with 

;  LDA,   PHft  instructions,    If  an  immediate  number 

;  1  5   spec  i  f  led   (  "rvalue"  )  ,    the   numbei'    j.  g  put 

;  on   the  stgck   nflth  a  PEft   i  rsi  t  r  u  c  t  mn  . 

MflCRD 

*LftB  PushWord  iValue 


LCLC  4CHAR 
iCHflR  AMID         *ValLie,1.1    ;&et  character 

fliF       "iCHfiR'f-"*" , .  immediate: 


CLflB  LDA  tValuff 

PHA 

MEHT 


.  IMMEDI ATE 


iCHAR 


AMID 


PEA 


&CHAR 


MEND 


;  PuahLong  Value 

;  Pushiong  j'Valae 

i  Thia  macro  pushes  a    lang  word  on  the  staclc.    If  an 

;  address   is  specified  ("Value"),   Ihia   is  done  with 

i  LDftf  PNA,  LOA,   PHfi   in  a t r uc t i or s .    If  an  immediate 

;  number    1 1  sptc  l  f  l  ed   (  "'Value^* )  ,    I  h«?  number    is  put 

1  on   the  slack    with   two  PEA   1      t r uc 1 1 c n 5 . 

MflCRD 

tlab  PUSHLDNG  ItValue 


LCLC  SCHflR 
iCHAR  AMID        (Value, 1,1    jCet   l^t  character 

flIF  "ICHAfl"'"*",. IMMEDIATE 


64    Programming  the  65816  Microprocessor 


LDf^ 
PHfl 


iValue 


MEKT 


.  IMPlEDlflTE 


Slab 


DC 
DC 

DC 
DC 


11  'IF"4i 

12<  (l.CHAR),''iei 
11  '  JFt ' 
1^' ACHARi 


PEfl  opcode 
ftddress  high 
PEA  DpcQide 
Addr<e94  lew 


PuahPtr  Label 


;  pLish  a  four  byte  point-Br  on  the  ^t^ck- 

liab 
Slab 


MftCRQ 

PLishPtr  SLabel 


DC 
DC 
DC 
DC 

rtEND 


1 1  '  tF-l ' 

12"{iLabel]|-16i 

11  'tF4' 

12 ' iLabel ' 


PEfl  opcode 
Address  high 
PEA  opcode 
Address  low 


PopLdng  Datiaflddr 

Th 1 5  macro  peps  a  long  word  off   the  stack 

ard  stores  il  at  Dalafldd"-  ard  Us taOdtJ r  +  ^ . 

MACRO 

Slab  PcpLong  tDeTa^ddr 

Slab  PLA 

STfl  iDataAddr 

PLA 

STA  tDstaflddrt? 


PopUlord  DataAddr 

This  macro  pops 
and  stores  il  at 


Lizard  off  the  stack: 
Da lafiddr  . 
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4l«b  PopWord  4Dstaflddr 

STft  iDataAddr 


J    STR    'a  siring' 

i    Stares    the    specified    charattec    string    m  memory 
preceded  by  s  length  byte. 

MACRD 

(LSB  STR  *5lr  iTig 

*LflB  DC  II  'L:  tStrmg' 

DC  C'ftSU  ing" 

MEND 
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CHAPTER  3 


Using  the  gs 
Tools 


Owr  tliL-  srvciiil  \t"arh.  Apptr  lias  s|K"ii!  Lniisidrrulili.'  tiiiic  and  riu-rRv  dcvt'l- 
opinn  aiitl  pnIlnotili^  wfnU  it  ctjii'^ii.lfr'i  In  hf  ihr  ideal  int  tlnxl  nf  comtnuPiK-ulinn 
bftwi-fii  L-(iiiipiiUT  iiNLT  and  a  luinptittT  jinigrajii.  Tin-  diastii  iia-lhutl.  CiillL'ri  ii 
u!^e^  mterfaci:  wa^  first  popuKirizi-d  on  the  Lisn  (later  renamed  the  MatiiUnsli  NL! 
atitl  the  VlLK-iiitiisIi.  Il  is  iiased  on  a  tl<'slil()p  metaphor  which  gOL-s.  fvoniethiiig  hke 
this: 

■  The  screen  is  the  desktnp 

•  Pfc'torial  itons  iiii  the  s(.r<?eii  rt'pit's<"nt  nhjccts  ovi  thr  desktnp  (such  as  file 
fiilders  mid  ddcks) 

•  Kc;e  tun  pillar,  overlappahlic  windows  represent  papers  tJii  the  desktop 

•  Pull-dowi!  iiK-iujs  at  the  top  ol  the  screen  represent  drawers  in  the  desk 

Such  a.n  inteifate  rcquirir's  a  "hand"  frvr  (juickly  sclcttinfi  papers  and  ntht^r  ubjeets 
an  the  desktop  and  for  miivinn  ihcm  oiind;  the  computer  s  hand  is  the  mouse.  Tt> 
select  Lin  nhjct  I  u  ith  the  minisi*.  jnovc  the  mtfuse  pointer  over  the  nhject  M  icon  and 
click  i^prcs.s  aiid  release!  ijic  iiiiiu\c  huttiiii.  To  diLii;  an  oiijcct  Iti  Linothcr  part  ul  the 
screen,  mnv'e  th<"  moose  pointer  over  the  olijcct,  press  the  mouse  button,  move  the 
mouse  while  fioldinji  the  hiitttm  dowu,  and  tiien  release  the  button  when  the  ohjett 
is  whtrc  you  wnut  it  to  hi-, 

A.  complete  description  of  the  desktop  envirnnment  can  be  found  in  Apple 
Ctnnpntcr-  Inc/s  Hiiiu^in  Intvrfiicr  Giin!vliut'-i.  {Sec  appendix  S.)  Be  sure  to  read 
thii  licjok  lielorc  atteunitinj;  In  develop  profe.ssionjl-<jualit>  stjftware  for  the  LIS. 

To  promote  the  use  of  the  desktop  cun  ironment  un  the  Apple  provides  an 
estensi^e  set  of  software  tcmls  tlut  pro^rdinmers  can  use  to  manaf;e  all  aspects  ;>f 
the  interfkce.  Some  of  these  tools  are  Iniilt  into  the  KOM,  others  are  loaded  into 
HAM  frozn  disk  when  an  application  Ixei^ins  Co  run.  The  iivailability  ol  these  tool^ 


means  most  cs-specific  programs  wlJl  use  them.  As  a  result,  users  can  concentrate 
on  masteritifi  ihe  uniqm'  portions  of  a  new  |)r!i)/riim  instead  of  its  user  interi'acc. 

As  will  he  distussed  hclow,  there  are  al^u  timh  thfit  i>erform  standard  operations 
more  directl>'  relnted  to  the  operating;  system  than  to  the  desktop  interface:  math- 
ematical calculations,  intcrac-tions  with  I/O  devices,  memory  management,  and  so 
on. 

The  GS  tools  are  dimply  a  series  ol  suhrnutities  tailed  functiurui.  For 

ctmvenieiice,  the  functions  iirr  divided  into  several  logical  groups  ealled  fim!  .wts; 
the  functions  in  a  particular  tnnl  sel  |Jerft)riii  the  same  g<*iieral  type  of  operation: 
memory  managCTiient,  window  handling,  niemi  handling,  and  other  tasks. 

This  chapter  dehtribcs^  ihv  toiil  sets  that  are  ava.ilahl('  on  the  US  and  shows  vnii 
how  to  access  them  frcwn  within  programs.  The  pnjccs'i  of  writing  new  tuol  sets  fmni 
scratch  and  making  them  ttvajlable  to  your  appli<.'ations  is  also  covered. 

TOOL  -SET  SUMMARY 

TaLle  3-1  shows  what  tool  sets  arc  available  iur  the  cs  and  yiives  the  names  iif  the 
cnrrt-sptnidiiij;;  AFW  macro  dffinitioii  files.  It  also  indicates  whether  the  tool  sets 
are  heated  in  ROM  ur  whetlur  tbc>  riuisl  be  loaded  intn  RAM  from  disk  by  the 
application-  (KAM-hased  tool  sets  mu'^t  be  stored  in  the  SYSTEM/TOOLS/  suhdi^ 
recton  of  the  boot  disk.  See  chapter  10  )  Keep  in  mind  that  as  huy.K  are  eradicated, 
Apple  will  begin  to  move  more  of  tht^  KAM-based  tooli  to  ROM  in  order  to  free  up 
disk  space  and  iniprn\e  proj^ram  perfnrmance. 

Laler  chapters  will  examine  most  of  the  common  GS  tool  setii  hy  descTlbilig  their 
{(inclii^ns  and  showing  liow  to  use  theiti  in  programs.  This  chapter  merely  summa- 
rizes the  main  features  of  each  of  the  standard  tool  sets. 

Tool  Locator 

The  Tool  Locator  is  responsible  for  the  smooth,  concurrent  operation  of  all  the  CS 
tool  sets.  Must  applications  use  it  explicitly  for  only  two  reasons:  to  load  RAM-based 
tool  sets  from  disk  and  to  install  custom  tool  sets.  Many  tool  sets  use  the  Too! 
Locator  implicitly,  primarily  to  save  a  pointer  to  a  gpneral-pur]5ose  workspace  in  a 
Work  Area  Pointer  Table  (WAFT)  maintained  by  the  Tool  Locator. 

Memory  Manager 

An  application  ii.%es  (he  Memory  Manager  to  allocate  blocks  of  memory  that  have 
not  previously  been  respr-'ed  by  the  operatinK  system  or  another  application.  This 
mean.'i  progranimerti  no  longer  have  to  worrj'  about  memory  conBicts.  The  other 
major  function  of  the  Memory  Manager  is  to  free  up  prcvinusly  allocated  blocks, 
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Table  3-1;    The  Standard  Apple  lies  Tool  Sets  ^ 

Tool  Set 

Number  Toot  Set  Nome  APW  Macro  File 

1  *Tool  Locator  M 16,  LOCATOR 

2  *Meiiioi:>'  Manager  M16.  MEMORY 

3  *Misccllaneous  Tool  Set  MJG  MISCTOOL 

4  +Quicl(Draw  II  Mlfi.QUK^KDRAW 
J5  *Desk  Manager  MI6.DESK 

6  *Event  Manager  M16.EVENT 

7  ^Scheduler  M16.SCHEDULEH 

8  *SQmid  Manager  M16.SOUND 

9  "DeskTop  Bus  Tool  Set  M16.ADB 

10  *Flo;itins-PQiTiit  Numerics  (SAXE)  M16.SANE 

11  *Integer  Math  Tool  Set  M16.INTMATH 

12  *TcsI  Tool  Set  MIG.TEXTTOOL 

13  *RAM  Disk  Too!  Set  [internal  use] 

14  Window  Manager  M16.  WINDOW 

15  Menu  Manager  M16.MENU 

16  CoQtrol  Manager  M16.CONT110L 

17  System  Loader  M16.LOADER 

18  QuickDraw  Auxih:uy  Tool  Set  M16.QDAUX 

19  PrhU  Manager  Mlfi-PRINT 

20  LineEdit  M16.LINEEDIT 

21  Dialog  Manager  M16.DIALOG 

22  Scrap  Manager  M16.SCJR.\P 

23  Standard  File  Operations  Tool  Set  M16.STDFILE 

24  Disk  Utilities  [none] 

25  Note  Synthesizer  M16.N0TESYN 
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Tabic  3-1:  Contiiiiifi] 


Tool  Set 

.\itmher  Tool  Set  Name  APW  Macro  File 


^fi  Note  Sequencer  [none] 

27  Font  Manager  M16.FO^fT 

28  List  Manager  M16.LIST 


note;  Tool  sets  tnarkcil  by  mi  asli  rink  ["!  are  in  ROM. 


Mi'scellaneouji  Tool  Set 


Applications  do  not  often  use  Ihi-  Miscelliinfouji  Tool  Sel  berausc  H  performs  Inw- 
levH  [asks  that  are  usually  liandlrd  by  the  operating  s\'steiii,  suth  as  assigning  ID 
tags  to  memory  blocks,  seHinp  tin;  date  and  time,  and  eiiablmg  interrupts. 


QuickDraw  11 

QuickDraw  II  is  the  largest  and  most  tomple.v  of  the  cs  to<5l  st-ts.  Tts  main  duties 
are-  to  perform  all  draw.'in^  OjDeratinns  on  the  .super  high- resolution  screen:  iictivities 
such  a.i  plotting  points,  drawinj^  lines,  fillins  shapes,  and  displaying  characters.  In 
addition,  it  control.^  pen  positioning,  defines  coordinate  systems,  and  changes  draw- 
ing piirameters  (such  as  color,  pen  size,  and  olht^r  characteristics). 


De&k  Manager 

The  Desk  Manager  allows  you  to  install  Classic  Desk  Accessories  fCDAs)  and  New 
Dfik  Acx:essories  {NDAsl  in  the  system.  A  CDA  is  an  acccs.sory.  iuch  3.s  the  Control 
fanel.  that  you  can  tall  up  by  pressinf^  [Control -Ope nApplp^ Esc  lro]n  the  keyboard. 
An  NDA  is  an  accessary  that  you  ran  call  up  in  a  desktop  cnviroanient  by  selecting 
its  name  fi-om  a  pull-down  menu. 


Event  Manaj;er 

Ccnerally  speaking,  an  event  is  thp  occlirrenL-e  of  a  condition  caused  by  an  VO 
device  like  iho  keyboard  or  l:he  mou.se.  The  most  cnmnion  events  ari^  the  pressing 
of  b  key  Of  the  mouse  button  and  the  release  of  the  itiouse  buttun.  Two  types  of 
events  arp  not  lied  to  I/O  devices  at  all — u|xlate  events  and  bittivate  events;  these 
events  ix.-eur  when  the  appearance  uf  a  window  needs  to  be  changed.  The  Event 
Manager  is  responsible  fur  keeping  track  pf  events  and  reporting  them  to  the 
applitatinn  when  requested  to  rio  so. 
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Scheduler 

The  Scheduler  prnvitlrs  ii  itu'r}i:ini^:!ii  fnr  t-nsnrinj;  that  a  hiisy.  inm-rfentmiit  pm- 
gram  mcKlvik:,  such  as  ProUOS  Ifi,  will  not  hf  ualltrtl  liv  it  pni^raiii  tlittl  fiets  tiiiitnil 
during  a  system  iiiti'rnipt  until  thf  iniidule  i.s  no  kjiin^r  ItiiiV,  Tht  uiiUii  llif  i)l  this 
tiTKil  s(=t  is  in  sfhi-diilin);  ihf  C(jntrii!-()pL'nAp|ile-EsL'  CKissil  Do>ili  AoLTSSOry  ilUor- 
mjil  As.  chapti-i  1(1  will  ilisL'uss.  yctu  will  also  uSf  il  wlw-ii  iiistallili^  Ltrtaill  typfS  (if 
inteniipt-handliuj;  suliroiitines  iiitii  I'roDOS  16. 

Sound  Manager 

The  Sound  Mana^tir  lets  you  conlrol  the  lirha^'iiir  ol  the  r:s's  Ensoniq  DOC  sonntl 
svnthesizer.  ll  also  includes  I'linrtions  fnr  acn'ssint;  thf  64K  PL^M  area  dedicated  In 
the  DOC. 

DeskTop  Bus  To«l  Set 

The  DcKkTiip  Ri\s  T(ml  Set  lets  you  eommumeate  with  ijipul  devit-es  connected  to 
the  Apple  DesikTop  Bus, 

Floating-Point  Numerics  [SA>JE) 

The  Floating-pomt  Numerics  tool  set  implcjoc-nts  the  Standard  Applt^  Nunieric 
Environnient,  It  is  made  up  of  a  group  of  fuiLctiuns  that  upplicatknib  ^an  um.'  to 
perform  fioatiiiR-ixiiTit  malhcnialieul  t)pfrationii. 

Integer  Math  TtH>l  Set 

The  InteHtT  Math  Tuo]  Set  contains  functionii  thai  permit  the  laatht-iiiatical  manip- 
ulation oi  iiiteser  uninlitTS.  This  tool  set  also  ennlaius  nine  mnvt-Tiient  nnmbrr 

cortversluu  utililleii.  wiuch  are  descrilicd  in  appendix  4 
Test  Tool  Set 

The  Te^t  Trnil  Sel  is  imporlant  In  projfrains  thai  wi^ih  to  usf  the  test  screen,  rather 
than  the  super  high  re  i^o  lot  ion  graphics  screen,  tor  output.  Wilh  this  fool  set,  d 
prdgram  ean  print  characters  to  the  screen,  much  as  tnidttional  lie  sol'tware  does 
You  can  also  usf  this  tool  !iet  In  redirect  character  output  to  d  printer  The  Text  Tot>l 
Set  is  act\ja.lly  iiuitt-^  general:  you  can  u^e  il  to  send  ehuraLteis  to  any  port  or  slot  or 
to  gel  input  from  any  port  or  slot  (or  direftly  from  the  keybuardl. 

RAM  Disk  Tool  Set 

This  tool  set  is  Ibr  use  hy  the  operating  system  only;  applications  must  not  u:ie  it, 
It  is  called  to  cuiitrol  all  operations  related  to  thp  RAM  Disk  device  you  tan  create 
with  the  Control  Panel- 


Tool  Set  Summartj  71 


Window  Matiiiger 

The  Window  Manager  is  resiJunsililtf  for  all  activifies  related  to  window^:  creating 
them,  destroying  t]:iem,  dragging  them  around  the  screen,  re-siaing  them,  and  so 
on. 

Menu  Manager 

The  Menu  Manager  Ltm tains  the  fiinctions  an  applicafiun  needs  tp  create  and  niaiia^t; 
pull-down  menus  in  the  desktop  environment. 

Contrul  Manager 

A  control  is  an  ohjcct  thai  can  be  seleeted  to  cause  an  tminediate  actitm  ur  to  set  a 
parameter  that  will  affect  a  future  action,  With  the  Control  Manajjer  you  can 
associate  various  t>'pes  of  controls  with  a  \vindow.  The  main  standard  tontrols  arc 
push  hutton;;,  checkhoxcs,  radio  bultons,  editable  test,  and  scroll  bars.  The  control 
manager  also  lets  you  define  your  own  HLiinlmis. 

System  Loader 

The  main  fimction  of  the  Syjitem  LoadcT  is  to  loiid  a  ProDOS  lf>  application  ffiletype 
S16)  Or  any  other  type  of  f  roDOS  IB  load  file  from  disk  into  memory  so  (hat  it  can 
be  executed.  It  also  takes  care  of  two  major  preliminary  steps;  determining  the  size 
of  the  application  and  reservinR  (with  the  Memory  Manager)  a  hkick  of  memory  at 
which  it  can  he  loaded-  (Some  applications  may  require  jiiore  than  one  block.)  The 
System  Loader  is  loaded  into  memory  when  ymi  boot  a  ProDOS  16  disk. 

QuickDraw  Auxiliary  Ttni]  Set 

The  Quickdraw  Auxiliary-  Tf>ol  Set  contains  additional  functions  for  the  QuickDraw 
II  tool  act 

FrinI  Manager 

The  FrinL  Miiinfrer  is  a  set  of  functions  that  lets  you  send  text  and  graphic^  to  a 
printer  instead  of  to  the  screen. 

LineEdit 

The  Line  Edit  tool  set  lets  }ou  t^dit  liiie^*  of  text  in  ii  manner  con.'ii.stf'nl  witli  Apple's 
user-interface  guidelines-  It  supports  standard  cut,  copy,  paste,  delete,  and  range- 
selection  operations. 
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Dialog  Manager 

The  Dialog  Manager  controls  the  use  of  dialog  and  alert  tioses.  Programs  use  these 
boxes  when  tlu-y  have  jmpiirlant  messages  to  display  or  wht^n  they  want  the  user 
lo  enter  information. 

Scrap  Manager 

The  Scrap  Manager  contains  fVint-tions.  For  transferring  data  lo  and  Iroin  a  data  stnrago 
area  called  the  diplxmrd-  U^inj;  a  cliphoard  make?!  it  pnsMible  tn  easily  Iniiisfer  from 
one  program  to  another,  or  even  helueeii  diFTerfnt  mt>dules  of  the  same  program- 
Standard  Fde  Operationfi  Tool  Sel 

The  Standard  File  OperatiaiiJ  Tool  Set  provides  _stiUidard  dialog  Ixixcs  to  be  used 
when  thL-  ;ipplieiitiuns  need  to  know  the  name  of  a  file  to  be  opened  or  saved. 

Note  Synthesizer 

The  N<ite  Synthesizer  lets  yoii  program  the  Ensoniq  DOC  sound  synthesizer  to  play 
musiral  nutes  with  uier-defiiH:d  instruments. 

Note  Sequencer 

The  Note  Sequencer  has  functinns  that  let  you  play  hack  a  user-definable  sequence 
of  notes.  The  frequency  and  duration  of  the  notes  can  be  act  by  the  iiipphuition. 

Font  Manager 

The  Font  Viananer  functions  let  you  manage  character  fonts  stored  in  tht^  SYSTEM/ 
FONTS/  direetory  on  disk.  Witli  this  tool  set,  an  appUcation  can  easily  load  and 
select  fonts  and  ehoose  font  attributes. 

List  Mandger 

Hie  List  Manager  lets  you  simplify  the  handling  of  lists  of  items.  The  items  eouJd 
represent  filenames,  &tritigs.  funis,  eulor  patterns,  or  any  other  group  of  data  ele- 
menti  that  have  the  same  row  hei^jht  on  the  graphics  screen.  The  items  in  a  list  can 
be  displayed  in  siich  a  way  that  the  user  can  move  through  the  hst  usinR  a  vertical 
scroll  bar. 

USING  THE  TOOLS 

Apple  has  developed  a  standard  tet-hnique  for  calling  any  function  of  any  tool  set. 
To  use  this  technique,  the  65Sltj  must  be  in  full  native  mode  with  16-bit  X,  Y,  and 
A  registers.  If  it  is  not,  an  enur  occurs. 
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Here  is  the  procedure  tu  tblluwi 


1.  Reserve  a  space  on  the  staelc  fur  the  results  returned  liy  the  fuiK-tinn  (if  any). 
You  can  do  this  witli  any  iiisLrui-'liuu  thai  pu^ht-s  daitii  on  !he  stack,  ahhnugli 
PHA  is  just  as  convenieni:  as  any  other. 

2.  Push  on  the  stack  all  input  parameters  required  h)'  th<'  function  (if  any), 
These  piriLinc-tcrs  can  be  nuineric  constants  (wurds  ur  lunji  words),  puintiTs, 
Or  handle!!. 

3.  Load  the  X  register  with  the  ID  number  for  the  fuiictiun: 

256  •   (funption  number)   +  Icol   ael  nurrber 

That  is,  put  the  tool  set  numhtr  in  the  low-ordcr  part  of  X  and  the  function 
huthIkt  in  the  high-order  part. 

4.  Make  a  long  subroutine  call  (with  JSL)  to  tke  system  tool  dispatcher  at 
SEItXXK),  [f  csllin^  a  function  for  a  user-defined  tool  set  {see  below),  call  the 
user  tcKjl  dispatcher  at  SE10008  instead. 

On  return,  any  results  are  on  the  top  of  the  jitack  and  miast  he  removed  with  one 
or  mure  pull  operations  (FLA,  PLX,  or  PLY). 

]f  an  error  tK:ciirs.  the  tool  dispatcher  sets  the  carry  flag  and  retunis  with  an  error 
code  in  the  accumulator. 

A  specific  cjcampW  will  make  it  easier  to  understand  what  is  involved  in  calling 
3.  funt'tiun.  Suppose  yon  want  to  Vise  [he  TaskMaster  function  in  the  Window 
Manager  ttKil  set.  This  fiinction  has  two  input  jmameterj  and  retums  a  word  as  a 
result.  Here  is  hi>w  to  call  it; 

iCreatt   alaclr    space    fpr    result  fujord) 

iPush  first   input  parameter  (word) 

;Pu5h  second  parameter  (high) 
1    ....    and   {  I  ovi )  . 

iFunctior  (high)  and   looi  set  [lQ*rl 
;Cail    the   syst em  tool  dispatcher 

;PQp  the  rpsull    i r 1 0  the 
;  two  bytes  begmnitig  at  Tt«e1?e5ult 

It  is  important  to  understand  precisely  what  is  happening  in  this  sequence  of  code. 
Because  the  function  returns  a  two-hyte  result,  tlie  first  step  in  to  push  space  for  it 
on  the  stack  with  a  PHA  instniction  (in  lull  native  mode,  this  decrements  the  stack 
pointer  by  two  bytci;  if  the  function  had  returned  a  four-byte  result,  two  PHA 
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PHA 

PEA 

IFFFF 

PEfl 

TaakRechIG 

PEA 

TaakRec 

LDX 

#*1D0F 

JSL 

tEtOOQD 

PLfl 

5Tf\ 

TheReaul t 

instructions  would  have  been  used  to  reserve  s|>aL'eJ.  Next,  eat-h  input  parameter  n 
pushtd  on  the  st^ick  in  iht  orclt-r  ciitliaU'd  hy  Ihe  fLmLtinn  definition-  In  the  example, 
the  first  paramctiT  in  ii  word-aized  constant  and  is  pn^ihed  with  a  PEA  instruetioii. 
The  second  paramete-r  is  a  liinp  address,  so  it  is  pnshetl  {hifih-order  word  fiistj  with 
two  successive  PEA  instniLtioiii. 

The  LDX  iiistriietinn  londs  the  X  register  with  the  tool  set  ($0E)  and  hintition 
($1D)  numbers  so  that  the  tool  dtspatcher.  callt-d  willi  tlif  JSL  $R100(X)  instruetiun, 
knows  tht  fuiietinn  tu  which  yon  want  tc^  pass  control. 

Finally,  the  result  if,  pullt-d  fVnm  the  atiiuk  vvitli  a  I'L.^  iiistructinn .  If  the  result 
was  a  twD-word  quantity,  you  would  pull  tT.nce  and  the  low-order  word  would  come 
off  The  stack  first. 

RcmcmlKT  tliat  when  yuu  use  a  func-tiuii  wfiieli  returns  a  result,  you  must  push 
space  for  the  result  on  the  stack  before  calling;  it,  and  you  must  remove  the  result 
when  tht'  funutiiin  ends,  Fiiilnrc  tn  follow  Iht-se  two  rnk's  will  pul  the  stack  out  of 
lci]ter  and  couid  eventually  causc  your  program  to  eraili. 

Data  Type!)  Used  by  Functions 

The  input  or  output  Jiarametcrs  of  a  fiinetion  L-an  be  one  of  thrcE  sizes;  byte,  word 
[twii  livtes),  or  loop  word  (four  bytes).  If  a  parameter  represent.")  a  numeric  qu^^intity 
(a.s  [jpposed  to  Lin  iiddrt-JiSl  its  data  type  is  said  to  bf  mlcacr  for  a  ward-sized  iiuinbej, 
Boiili'ait  for  a  true/false  word- sized  nuinlier.  and  tortg  inii'H'H'  for  a  kmp-word-sized 
number.  A  Boolean  parainetEir  is  one  that  is  true  {non-zcrti)  or  false  {zero). 

Note  fliiil  addresses  pa^ised  to  funLtious  are  always  four  bytes  long  even  lliough 
the  65*il6  uses  oidy  three  byteh  {2i  bits)  to  form  a  loot;  address.  The  extra  byte 
(always  ^.tW)  makes  sure  that  there  is  always  an  integral  number  ul  piiranieter  words 
csn  the  st;iek,  whit^h  makes  them  easier  to  access  with  word-^ized  (16-bill  operations. 

Tfie  data  l\pe  of  an  address  is  either  (Hiittii^y  or  Imncllf.  By  tuovenlion,  symbolic 
names  for  such  data  types  end  in  "Ptr  "  or  "Hndl  '  A  pointer  is  simply  the  address 
of  a  data  structure  somewhere  in  meniory.  A  handle  is  the  address,  not  ol  a  data 
struelure  itself.  l>iit  nf  ii  liiealion  iIkH  etHilaiiis  a  pointer  tii  the  data  structure.  Pointers 
and  handles  arip  described  in  !iiTaler  detail  in  the  next  chapter. 

Tool  Set  Macros 

Table  3-1  (see  above)  contains  the  names  of  ihe  .\P\V  maen>  definition  files  for  eaeh 
t;s  tool  set.  You  can  r-xtraet  the  miiern  definitiotis  ymir  p^J^^^JlIl  needs  with  the 
MACGEN  eonnii.j.nd  prior  to  asseniblini;  the  pmyrain.  As  e\plained  in  chapter  2, 
tlie  purpose  of  the  tuol  set  macro  files  is  to  assitjn  a  standard  s>'niboli(  name  to  the 
LDX/JSL  calling  sequenee  for  eaeh  tool  set  funeticin.  By  eon\ention,  all  function 
names  bcfiin  with  an  underscore  character.  The  name  _TaskMaster,  for  example. 
tL-for^  to  function  SID  in  trxil  set  SOD  (the  Window  Miinaser}, 
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APW  alsn  L'dinL-^,  with  a  SL-t  uf  gentral-ptirpose  mat-ms  in  the  M 16. UTILITY'  file. 
Thret-  (jf  thesi-  iikiltus  (PiishWorii,  Pusli Liirifi,  iinil  I'listiPtr]  are  piirtic iilarK'  useful 
for  puihing  piramt'tt'i  s  on  ihe  styck  prior  to  inakin^  a  tool  set  ruiiction  tall  and  arc 
iiimilar  ta  the  macTos  listed  at  the  end  ui  chapter  2. 

Tu  push  a  parnriiett^r,  list-  PiiaIiV\''ord  tJ'nr  words),  PushLoiig  (for  \nn%  w«rels!,  or 
PushPtr  {Utr  aildreh:,  ixiinterh],  PushWurd  and  PiiiiliLoiig  are  able  to  push  numhcrs 
stored  at  an  address  or  inimediale  tmnnbers; 


PiiihWord 

MyPsrm 

iPush 

the  word  al  HyParm 

PushWar  d 

#1  0 

;  Pu  ah 

a  t  0   {  inqmed  i  a  te ) 

PushLoTTg 

MyS  L  z  E 

:Puah 

the  long  ^ord  at  NySizE 

Pu  5  hLo  ng 

#t7FFFFr 

;  pLi9h 

a  I7FFFFF   { immed la te ) 

PuBhPtr 

;  Push 

the  addrc55  cf  HyDat^Sizc 

Nolk-L-  that  the  drRumtnts  for  the  two  macros  involving  immediate  nuinbpi-s  arc 
preueded  (jy  a  '*#"  s.ign. 

At  kisseiidily  time,  these  ttiacros  are  expanded  into  the  following  code  sequences; 


LDA 
PHA 


flyPa  rm 


PEA     1  D 

LDA 
PHA 

My  Si 


LDA 

PHA 

PEA 
PEA 

PEA 
PEA 


17FFFFF|-I6 
17FFFFF 

MyDfltaflreal-16 


jPiishUord    My  Farm 
;Pu5hWard  #10 

■,PuBhLong  #17FFFrF 
;  Pu^hPt  r  MyDfltflArea 


Notiw-  that  the  immeciiatc  forms  iif  Push  Word  and  Puf.hlj)ufi  push  the  toiislants  on 
thi'  statk  with  PKA  instniLtiin^s,  This  t-cmv-fnitnllv  avuidji  dt-silroyiiig  the  contetits 
of  the  A  rE'gisler  (or  any  other  registrr). 

Thf  PushPir  inatTo  pushes  the  address  lipecified  in  its  urffiiment  onto  the  stack 
in  fhc  sanif  w^y  lliat  tlie  immediate  ftirin  ul  PusliLxHip  [iiisheS  its  iiLuneric-  argnilient. 
In  fat^t.  thif  only  diflercntf  Isehvecn  PushPtr  and  FliahLong  is  that  PushPtr's  argu- 
ment d(»es  not  require  :i  leadinj;  numlier  si^ii. 

The  tw(]  inatjro_s  hstt-d  in  chapter  2  Ihr  removing  results  from  the  stack  were 
P[)p\Vord  ift>r  wnrdii)  and  PopLtms  (for  lim^  words).  The  argument  for  each  is  the 
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address  at  wliicli  iht-  result  is  lo  be  sinred.  For  fxainplf,  "PtjpWord  TheHesull'  is 
equivalent  to  the  fulluwiiig  cade  setiuenve: 

PLA 

STfl     TheReaull  PopWord 
and  Popljiny  MyAddri'ss  in  ccjui^ideiit  hi; 
PLfl 

5Tf(  MyAddress 

STfl  MyAddre55+2  iPopLong 

By  usinff  these  five  simple  pull  and  pop  iiiiicmK  ;md  tht-  Uio\  set  fuTicMKn  inatTus, 
yoii  ctin  make  >{iuf  source  code  miirt'  undcrstandaljlc  and  easier  ka  maintain.  In 
addition,  tlie  eliances  of  (■oininittiny  errors,  such  as  pushing  or  pulliiif^  two-word 
cju^iiititics  in  the  wroiiji  order,  art"  miiiiinizt?d. 

THE  TOOL  LOCIATOR 

The  first  tool  set  you  should  kiitiw  ahoul  is  the  Tod  LtJtator  because  it  inanagef;  aJI 
the  other  tool  sets-  Tlii'  main  fuTietimis  in  l5ie  Tool  Ltiealor  iirp  tjuminariyf'd  in  tahk' 
R3-I  at  the  end  ot  the-  chapter,  idnd  will  he  etamiiied  in  mnrr  detail  later  in  this 
chapter. 

Only  a  few  TonI  Locator  liinetiiKis  will  ever  be  needed  h>  most  upplieiitions.  The 
first,  TLStartup,  prepiires  the  Tool  L^teutor  tor  operation  and  imust  be  ealled  before 
usinfj  the  fmietiiHis  it  ^uppurtii  or  funetionii  nf  any  other  tool  set.  TLShutDowii 
"tiLrn.s  off"  the  T<h)I  Louitor  and  should  be  called  just  before  your  applieatiun  ends, 
after  the  |)rof;raiti  tails  the  ShiitDowii  functions  nF  an)'  other  tools  that  have  been 
started  up.  \either  TLiitLirtiip  ilur  TLShutOown  requires  any  input  paracneters, 
and  neither  return  :i  result. 

Tlie  LoadTools  fuiietion  loads  RAM-based  tool  sets  from  diik  iuto  memory  so  that 
tlieir  funetions  enn  be  fiilled  by  an  applicatinn.  Its  only  parameter  is  a  pointer  to  a 
tool  set  load  luble  n-oiitatiung  a  list  nf  the  ID  numtiers  and  version  nunibers  of  the 
tool  sets  to  be  lottded,  Tor  this  Inadins  scheme  to  work  properly,  the  tool  sets  must 
be  stored  tn  disk  files  hnvinp  names  of  the  form  TOOLxxx.  where  \\\  is  the  threc:- 
dipjit  decimal  number  of  the  tiKil  set.  In  additiuu.  these  Kles  must  be  Iwatcd  in  the 
SYSTEM/TOOLS/  subdirectury  of  the  (.tart-up  disk 

Here  is  an  example  of  how  to  use  LuadTjols  tu  load  twelve  standard  too!  sets 
from  disk: 

PustiPtr  LoadTahle 
_LnadToo I s 

LoadTable  DC  ;Number   of    tool  acts. 

DC         [P'14,0'  ;UindotaF  manager 
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DC 
DC 
DC 
DC 
OC 
DC 
DC 
DC 
DC 
DC 
DC 


12'  15  f a » 

12'  IG, 0' 
I2M8,0' 

:2M  g ,  0 ' 

I£i20 ,0  I 
12'£1 ,0 • 

1?'23,0' 
1 ? ' ?5 . 0  < 
I2'27.a ' 
I2'2e,0 ' 


Notici^  how  the  tool  set  load  tabit  is  constructed-  The  first  entry  is  the  iiuinhn-  of 
tiio]  set  entries  sEored  in  thp  labte.  Following  it  are  two  words  for  each  tool  set. 
The  first  is  the  tunl  set  numljcr  the  ieL-niid  is  the  miiiimiim  vcr-iiou  number  expcL-ted 
(a  value  nf  0  means  am  VL-rsion  will  do).  LoadTcmls  return'!  an  error  if  it  tannot 
IfKHte  the-  proper  versions  ol  all  tbe  tciols  listed.  (As  explained  below,  errors  are 
rt-corded  by  setting  the  LUrn  flap  aiid  putting  an  error  eude  in  the  act-umulator.] 
If  only  one  tool  set  has  tu  be  loaded,  usu  LuadOneToo!: 

PiishUlord  TSNum  ilool   ^st  nuihter 

PuflhWard  Version  ;versioi.  number 

_LQadQrveTDo  1 

You  may  want  to  use  LoadOiieToul  in  situations  where  the  applieation  can  function 
even  if  the  specified  tool  set  is  not  present.  For  example,  you  eoulcl  use  it  to  try  to 
load  the  Print  Manaser;  if  the  load  laih  [the  earr>-  flag  is  set),  the  application  can 
disable  al]  printing  related  commiinds.  If  you  l(jad  a  larRe  group  of  tool  sets  with 
LoadTool.';  and  get  an  error,  you  cannot  tell  width  tool  set  in  missing. 

K.^M-hased  tool  sets  loaded  into  memtiri  wilh  LoadTools  or  LnadOneTnol  remain 
active  until  you  eall  TLiihutDnwn  at  the  end  of  the  proj^ram  or  until  VGU  call 
UnloadOneToid.  Whereas  TLShulOown  removes  all  R.'iM-based  tools,  Unload- 
OneTool  remove!)  only  niie: 

PushUord  TSHLtm  itool    5et  rumber 

_Unl oadDnffToo 1 

Use-  UnloadOneToo!  when  you  are  ihrotish  iisins  a  given  tool  so  that  the  memory 
it  occupies  will  be  Ireetl  up, 

Yon  CiUinot  load  RWI-based  tmis  if  the  hoot  disk  is  not  in  a  drive   If  you  tr>' 
you  will  get  ProDOS  error  $45  (vuliinie  not  liiimdl.  To  recm  er  Irom  tliis,  you  should 
use  TLMoun(Vo]nnie  lo  display  a  dialog  box  asking  (he  user  to  insert  the  boot  di-^k- 
Tlie  application  can  tr>  again  when  the  user  clicks  the  OK  button,  or  it  lan  abort  if 
the  Cancel  button  is  clicked. 
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An  examplic"  of  how  to  use  TLMnimtVnliirinc  is  giv*"n  in  ihe  !?TAKDARD.  ASM 
program  in  listing  )-  Because  TLMountVoJume  rfc[iiirL's  <^uic-kDraw  atitl  the 
Event  Manager  to  hf  active,  do  not  try  to  load  tools  until  after  you  have  started  up 
QuickDraw  and  the  Event  Manager. 


THE  STRUCTURE  OF  A  TOOL  SET 

Each  GS  tool  set  may  contain  up  to  255  hmcticms,  numbered  from  1  to  255.  A 
&QcCioD  number  of  0  is  not  allowed  By  convention,  the  first  eight  functions  must 
perform  certain  specific  actions  dictated  by  the  operating  system — other  functions 
(.■an  do  aiiythitig  the  designer  of  the  tool  set  wants  them  lo  do. 

Of  the  first  eight  finiclions.  two  are  reserved  for  future  expansion  (#7  and 
Here  is  what  the  other  six  stantWd  funt-tions  do; 

Bootlnit  (#1!.  This  function  performs  any  preliminary  initialization  of  the  tool 
set  which  might  be  nCTessary.  Tine  system  monitor  firmware  calls  it  when  the 
system  starts  up  or,  if  the  tool  i.s  RAM-bastd,  when  the  tool  is  first  loaded  fi-cim 
disk.  Applications  must  not  call  this  function. 

Startup  (#2).  This  funotioii  prepiir.es  the  tool  set  for  action.  An  application  must 
caJl  it  hefure  usiiiR  any  other  functioti  ii^  thp  tool  set.  Many  tool  sets  require 
input  parameters,  (or  their  Startup  hinctions;  a  common  piu^iimeter  ii  a  bank  300 
address  used  by  the  too!  set  as  the  base  of  a  private  direct  page. 

ShutDown  (#3).  This  function  releases  any  memory  space  allocated  by  the  tool 
set  since  ittart-up,  including  inemnrj'  pointed  tn  by  the  wurk  aren  pointer  table 
{the  WAPT  15  described  below).  An  application  should  call  this  function  just 
before  it  ends. 

Version  (#4).  This  futictioti  returns  the  version  number  of  the  tool  set  (a  word), 
It  requires  no  input  parameters,  so  the  calling  seqoenee  is: 

PHP  japace  for  result 

—xixVers  i  or 

PL  A  •P°P    Iti*  version  number  result 

Thp  niajor  vprsinn  numhtT  is  in  the  hiyh  bytt'  and  the  min^nr  version  number 
is  in  the  low  hyte  <jf  the  result,  if  the  tool  set  in  in  the  prototype  stage,  the 
high-order  bit  (if  the  hi(j;h-order  byte  is  set  to  1. 

Reset  (#5).  This  function  returns  the  tool  set  to  a  known,  default  state.  It  is 
called  when  a  system  reset  occurs. 

Status  (#6).  Thi.s  function  returns  true  (non-zero)  if  the  tool  set  is  active  and 
false  (zerut  if  it  not, 
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of  these  six  standard  fuiittions,  only  two  of  thein.  Startup  and  ShutDown,  are  really 
needed  by  most  applications.  In  latrr  chapters,  when  specifiL-  tixtl  sets  are  discussed, 
these  wili  be  die  only  reser%"cd  functions  mt^ntioned.  Keep  in  mind,  however,  that 
die  Boollnit,  Version,  Reset  and  Status  hjnctions  are-  always  present — they  just  are 
not  used  often. 

Ahuost  every  program  you  write  for  the  cs  will  be^in  by  loading  RAM-based  tool 
sets  from  disk  and  calling  the  Startup  fimction  fur  each  too!  set  the  program  luifCs. 
When  a  program  ends,  it  will  L-all  the  ShutDown  function  for  each  too!  set.  To 
simphly  these  operation^!,  yiiu  shuuld  develop  a  standard  program  subroutine  like 
the  one  in  the  STANDARD, ASM  progrim  in  listing  3-1  and  include  it  in  your 
pro-am  sQurce  file  with  the  COPY  directive. 

STANDARD. ASM  has  twu  entry  points,  DoStartiip  and  DoShutDown.  Call 
DuStartup  at  the  be^rinning  of  a  program  to  load  all  tools  and  to  start  up  tool  sets 
in  the  proper  order  [The  order  Is  important  because  some  tool  sets  rely  On  tlie 
presence  of  others  before  they  will  work  )  Call  DoSbiitDown  tu  shut  down  all  the 
tool  sets  and  exit  the  program,-  Depending  fsn  the  program  you  are  developing,  you 
may  want  to  modify  STANDARD,  ASM  to  add  or  eliminate  the  group  of  tool  sets  it 
uses.  If  you  change  the  I-fladTnols  tool  tabic,  be  sure  to  set  the  leading  count  word 
("11"  in  ihe  eKuniple}  to  the  proper  value.  You  will  also  have  to  modify  the  tool  set 
Start-up  and  shut-down  sei|uence.*. 

As  li.sted,  STANDARD. ASM  itarts  the  application  up  in  the  640-by-200  graphics 
display  mode-  To  set  up  32l}'by-200  Rmphics  instead,  change  VidMode  and 
XMaxClamp  tn  SCO  and  320,  respectively. 

Notice  that  STANDARD. ASM  also  assigns  several  global  symbolic  labels  to  nu- 
meric constants.  Tliis  is  LDnvenieot,  lieeause  it  forces  you  to  use  the  same  labels  in 
all  your  programs,  tlius  making  them  easier  to  read. 

DEVELOPING  YOUR  OWN  TOOL  SET 

Associated  with  each  tool  sell  is  a  table  of  pointers  to  each  of  its  Junction  handlers, 
in  function  number  order; 

Number  of  functions  plus  I  (4  bytes) 
Address  of  Boollnit  Junction  minus  1  [4  bytes) 
Address  of  Startup  fiinction  minus  1  (4  bytes) 
Address  of  ShutDown  function  minus  1  [4  bytes) 
Address  of  Version  function  minus  1  (4  bytes) 
Address  of  Reset  function  tninui  1  (4  byCes) 
Address  of  Status  function  ininu.s  1  (4  bytos] 
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Address  of  Reserved  function  minus  j  [4  bytes) 
Address  of  Reserved  function  minus  1  (4  bytes) 
Address  of  Functinn  #9  minus  1  (4  bytes) 


Address  af  Function  #n  minus  1  (4  bytes) 


This  is  called  *  fiJnt'tinn  pointer  tablf  (FPT). 

To  Install  a  new  tool  "JCt,  you  miiNt  in.sert  a  pointer  to  its  FPT  in  one  of  the  t<io! 
pointer  tables  [TPT)  maintained  by  the  Ttml  Loeator  (tbere  is  a  system  TFT  for 
standard  system  tooK  iiiid  d  ust:r  TFT  for  ust^r-defined  tools).  Do  this  with  thr  Ton! 
Locators  SetTSPtr  function: 


PashWord  ^tSOOfl  ;9DQ0  =  La9er.   0  =  syalem  TPT 

Pu^hWiprd  #213  |Thi5  ii  ttie  tool  set  number 

PiiEhPtr  nyFPT  jPoinler  to  new  FPT 

^SetTSPtr  jln^tall   poirle-r    in  TPT 


The  tool  set  number  L-an  be  any  number  from  1  to  255  that  is  not  already  in  use  by 
another  active  tt»«il  set. 

The  fir-it  word  pushed  on  the  stack  is  the  SystemOrUser  word!  It  indicates 
whether  you  arc  dealing  with  system  tool  sets  [$0000)  or  user-dcfinc'd  Iwd  sets 
(S8000),  Toiil  sets  that  art  not  just  replacements  for  existing  system  tool  sets  should 
be  added  to  the  user  TPT. 

Tlie  funttinn  hajidlers  pointed  to  by  the  FPT  can  he  located  anywhere  in  memory, 
but  they  eannut  be  ailuwed  to  mowe  because  the  pointers  to  them  would  becoine 
invalid.  The  code  fur  J  function  should  be  re-entrant,  if  [wssiblc;  that  is^  the  function 
should  work  even  if  it  is  interrupted  and  called  by  an  interrupt  bandlr^r  or  a  Classic 
Desk  Accessory.  If  it  is  not,  the  function  must  increment  the  Scheduler's  busy  flag 
when  it  ^ets  control  by  perfurming  d  jSL  SEJ0064  instruction  in  full  native  mode. 
If  it  does  this,  it  muMl  decrement  the  busy  flag  on  cuit  with  a  JSL  SEUX16S  instruc- 
tion. Fntperly-designed  interrupt  handlers  will  not  make  tool  set  calls  when  the 
busy  flat;  i^;  non-zero. 

When  a  function  handler  gets  control,  the  65816  is  in  full  native  mode,  and  the 
stack  is  configured  as  follows: 
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psromelers 


SP+7 


JSL  Return  Address 


J5L  Return  Address 


<  stock  pointer 


The  last  of  the  two  3-b>ic  return  ^tldre^ses  is  caused  hy  a  JSL  from  the  lool 
dispatcher  to  the  tiinc-tion  liaiidler  Tlie  Hrst  Is  caused  by  the  JSL  to  thv  tool 
dispatcher  (at  SElOfKlfJ  or  SEICXWl  H^cM'. 

I  [lis  means,  that  the  parameters  pushed  «in  tlic  stack  by  ihe  application  licfnre  it 
calls  the  tCKjl  di^iatcher  begin  at  S  P  +  7  (7  bytes  pii,st  the  current  stack  pointer  valnej, 
Note  thai  the  offset  i,^  7.  not  6,  because  SP  [wints  ta  ihe  first  byte  past  the  last 
return  address,  not  tn  the  return  addre;^^  itSfll. 

•  WarninK!  These  offsets  remain  valid  only  if  the  function  handler  does  nut  push 
am  thiny  on  ihe  stack  after  gaining  control.  If  it  dcies.  use  uffKetii  that  take  this 
into  accuiniL 

To  access  parame lers  passed  uu  the  slack  in  this  way,  use  the  stack  relative  address- 
ing mode,  "sr.S  Suppose,  lur  example,  that  the  function  has  twu  input  parameters, 
the  first  lieinR  a  word  and  the  second  a  lon^  word,  and  the  lunctioa  returns  a  word 
result.  To  read  the  first  paranietcr,  nsc  the  instruction; 

LlJfl  11  ,S  tst  parame'ler 

The  ufiset  of  1 1  ii  the  sum  of  the  basic  offset,  7,  and  the  space  (x-cupied  hy  all 
parameters  pushed  iiller  the  first  parameter  (4  bytes  for  the  simile  lon^  word 
parameter  in  this  example).  The  operands  fur  accessing  the  second  parameter  wmdd 
be  7.S  (low-order  word)  a.nd  9.S  (bigh-order  word}. 

The  function  handler  returns  a  result  by  storing  it  directly  into  the  space  for  the 
result  on  the  stack.  In  this  example,  this  space  is  iit  a  kicatiun  givfn  by  SV+  13  (the 
address  of  the  first  parameter  pushed  plus  the  size  of  the  first  parameter). 

Before  it  finishes,  ii  fimctitm  must  remov  e  all  input  p^irametcrs  [but  not  the  result) 
from  the  staLk.  It  can  dii  this  by  moviiii^  the  two  r+ftom  addresses  to  positions  x 
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byles  hightT  in  meiiiory.  where  x  is  the  tolal  siyc  of  all  the  input  ptirL-imcTcrs.  Tlte 
stack  pnintL-r  musl  thfn  he  iiicreinpiited  hy  s  bytei  hefore  thi-  funttioii  cnd-S.  Fur 


itistaiite. 

if  tliere  arc 

10  bytes  of  pjriiiiieters,  you  would  us*?  the  rollow-inp 

segment: 

LDA 

5  ,  S 

;M;ove  SP+1    through  5P4B 

STA 

IS.S 

;    (the  two  ftturn  addre^se^] 

LDA 

;  up   10  bytes   to  5P+1S 

Sift 

13, S 

LDA 

1,S 

STA 

1  1  ,s 

TSC 

: Pu t   5P   I n  A  regist er 

cue 

#10 

;  .  .  .    add  10    to  5P 

TCS 

;Save  new  SP 

A  function  reports  emirs  by  setting  the  cam'  flag  and  storing  an  error  code  in  the 
A  register  before  ending  with  nw  RTL  inslrucl!t>n.  Hie  error  t'fwle  acliially  nceupies 
tlie  lower  S  hits  of  the  A  register;  the  upper  H  hits  hDid  t'hc  tmtl  set  number.  The 
assignment  of  error  ttmditions  to  ernir  L-odes  is  up  to  the  drsi^ner  of  thr  function. 

If  no  error  occurs,  a  function  rctunis  with  the  A  registcT  zeiued  snd  the  tarry 
flag  clear.  A  neat  w:iy  of  setting  the  carry  flag  properly,  error  ur  no  error,  is  to  exit 
with  a  CMP  #1,  RTL  instruction  sequeiite. 

Note  that  a  fnnetiim  need  not  presen  t'  the  euntents  of  the  X  and  Y  refiisters- 
Tlic  direct  page  and  data  hank  (and  c«dc  bank)  registers  cannul  change,  however: 
they  niuat  he  the  same  on  exit  iis  on  entry  Of  tlie  statn^i  re|;ister  hits,  m,  X.  c,  and 
I  must  be  unchany^cd  and  the  deeimnl  mode  fias  must  be  zero. 

Error  Codts 

Error  code.*  from  $0001  to  5000F  are  reserved  for  use  by  the  function  dispatcher. 
Of  these,  only  two  are  currently  used: 

*  0  0  0  1        The  tool  set  does  not  e.\isl 

$  0  0  0  2      The  tool  set  hinciion  dues  not  exist 

The  function  dinpateher  may  also  return  i  $FFFF  code;  this  means  that  the  call  to 
the  dispatclwr  wiii  not  made  in  (ulil  native  mode, 

Error  codes  retunied  by  functions  themselves  range  from  $xxOl  to  $xxFF.  where 
ftx  represents  the  too!  st  t  number.  One  of  these,  SsxFF,  has  a  special  meaning, 
namely,   the  function  is  not  implemented." 
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Work  Areas 


A  tuttl  set  may  require  a  private  wtirk  area  in  which  it^  functions  can  ^tore  config- 
urtCion  information  a.nd  other  data  which  niusi  [je  ^avpil  befween  functinn  calls.  If 
the  work  area  is  notlcicatrd  in  bunk  S0(],  function  #1  nftinc  tool  set  (Bootlnitt  .should 
reserve  the  spate  f.ir  it  with  (he  MenKjr>  Manager  {see  chapter  4), 

Bank  $00  areas  are  dealt  with  diHtrenlly  because  they  arr  prime  real  estate.  Bank 
$00  is  the  only  bank  in  which  a  direct  pa^e  can  be  set  up.  By  ranveiition,  if  a  tnol 
set  needs  direct  page  space  fur  a  work  area,  the  appiicatioji  must  allocate  it  and  pass 
its  address  to  function  #2  (Startup), 

The  tool  set  must  place  a  pcfinter  to  its  work  area  in  a  table  called  the  M'ork  Area 
Pointer  Table  (WAPT)-  (The  pninter  is  zero  if  thf  tool  set  dues  not  use  the  WAFT.) 
It  can  do  thii  with  the  Tool  Locator  s  SetWAP  junction.  When  a  function  handler 
takes  control,  the  entr>'  in  the  WAPT  is  always  in  the  A  [low-nrdcr  word)  and  Y 
[high-order  word)  registers. 

If  the  work  area  is  in  bank  $00,  the  first  thinR  the  ftuictioii  handler  should  do  is 
save  the  current  contents  of  the  direct  page  register  on  the  stack  and  set  the  new 
direct  page  to  the  work  area: 

P^fD  ^Save  direct   pag^  register 

TCD  ;"C"    (16-blt   A   register)   holds  d.p. 

Becaus:e  this  pushes  an  extra  word  on  the  stack,  the  address  of  the  lait  parameter 
passed  to  the  function  is  .SP  +  9  and  not  SF  +  7. 

Before  returning  to  the  tool  dispatcher  with  am  RTL.  restore  the  previous  direct 
page  with  a  PLD  instmction. 

A  USER-DEFINED  TOOL  SET 

The  program  in  listing  3-2  shuw^  how  [o  install  a  user-defined  tool  set  called 
TimeTools.  The  program  does  this  by  passing  a  pointer  to  the  tool  set  function 
pointer  table  to  the  SetTSPtr  functinn.  This  table  holds  pointers  to  the  eighl  standard 
functions  every  too]  set  must  support  and  to  one  ippcial  fuuLlion  cidled  DayOftVeck. 
You  can  use  the  DayOfWeek  function  to  return  a  character  string  containing  the 
name  of  the  current  day  of  the  week. 

The  start-jp  function  for  the  new  tool  set,  TTStartup,  expects  a  direct  page 
address  (a  word}  to  be  on  the  stack  when  it  is  called.  It  places  this  address  in  the 
WAPT  using  the  SetWAP  function.  None  of  the  TimcTools  actually  use  this  direct 
page  area;  the  purpose  of  requiring  it  is  simply  tu  illustrate  how  to  deal  with  work 
area  pointers.  The  TTShutDowu  functinn  clears  the  WAFT  entry  for  the  tool  set 
to  0, 

The  rrStatus  function  returns  &  Boolean  (word)  result  indicating  whether  the 
TimeTools  are  active.  It  returns  true  if  the  WAPT  entry  ts  non-zero  (which  means 
that  TTStartup  has  been  called). 
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The  TimeTiKils  too]  set  has  one  noii-reiiuired  lunclion,  DayOfVV'eek.  which  is 
asiignt-d  til  function  #9,  It  expGi'ts  Hnv  input  pafiimeterj  a  poinler  to  a  10-bytc 
buffer  allcKTcKecl  Ii>  (he  applifatian  calliiLfT  ilie  riinction,  DayOfWeek  returns  a  char- 
acier  strin^j  in  this  buffer  desmbiiiR  the  day  iif  ihe  week. 

DayOfM'eek  detenniufs  tht  day  oi  the-  wet-k  by  Ciillliig  ReadTimcHcx.  a  hinctioTi 
ill  the  MiiiLellaiieuu!^  timl  set  thai  rt'turiis  all  lime  and  date  parameters  in  binary 
form  (see  chapter  5).  Il  ihcii  takes  (he  totle  ibr  day  of  week  (1  =  Sunday,  2  = 
Manday,  und  so  orij,  toiiverts  it  to  aii  ASCEI  .ciiended  string;,  and  plaws  it  in  the 
bufl'er,  preceded  by  a  Icngtli  b>  te.  [t  then  removes  thr  input  parameter  from  the 
staek  and  returns. 

Notice  that  CetDayOfWeek  reluriis  an  (^rror  code  iif  1  if  it  rectHvcs  a  day  of  week 
code  which  is  0  or  above  7,  It  dws  this,  by  pultinS  thr  error  ttidp  in  the  aecumulatur 
atid  settinp  the  i:arr>'  flag  by  toinpariug  the  acfuniuLittir  with  I. 

Once  the  TinieTook  tool  set  is  installed,  yuii  e^n  call  its  funetiiins  fruin  am-where 
inside  the  installation  pni(;rjni.  To  tal!  the  Day(.>f\Veek  funetion,  fur  example,  use 
the  fulliiwing,  calling  sctim-nc-e: 


Piu^hPtf  [>OUJ_Bu-f  f  er 
LDl  #(0301 

RTS 


1 Pci  nter  to  bu  f f  er 
;  Fune t ion  9  /  tool 
i [not  E1000D! ) 


5&t  I 


DQU  Buffi?''  Q5 


1  0 


iSpacp    for    length    +  name 


The  program  in  lislinj^  .1-2  talis  DayOfWeek  in  this  way  before  displaying  the  day 
of  the  week  on  Ihe  yO-Loluimi  text  streen. 

Notice  that  the  }SL  in  this  example  in  to  luc-iSitiun  SiillXJtW,  the  entry  point  to 
the  user  huRtion  disijatcher,  nut  to  luciilion  *l£l(KHXI 

It  is  iinportiiul  to  reiili/e  thai  you  ciimiut  use  the  TimeTools  tool  sel  from  another 
application,  because  the  meiaory  il  occupies  is  purged  when  ihe  inslallatiou  program 
in  listing  3-2  endi.  In  any  event,  the  user  tool  pohiter  table  is  cleared  when  the 
TLStarlup  or  TLShutDuwu  huictions  are  called. 

To  allow  a  custom  tool  set  to  be  used  by  any  application,  you  must  install  it  in 
the  system  tool  poinler  table  To  do  this,  first  choose  a  tool  set  uumher  lha[  is  nut 
already  nscd  by  any  other  RAVt-  or  HOM-biyied  lool  set.  Then  prepare  a  source  file 
containing  just  the  code  defining;  the  tool  set-  For  the  tool  set  in  listing  3-2,  for 
example,  retain  the  TonlSet  c-ode  scgtiicnt  only,  chang^^  TS_NUM  to  the  selected 
tool  set  niiinlK'r  and  chanae  L'serOrSys  to  $()(J()0  to  mark  ihis  as  a  sysleiji  tool  set. 

Next,  a.ssendjk"  and  link  ihe  .snurce  file  iind  then  change  the  file  type  code  i>f  the 
EXE  file  created  to  SBA  usjnfj  the  .^PW  FILF.T>"PF  cnnitnand  (PrnDOS;  16  rec- 
ognizes only  SBA  files  as  systfin  ((MhI  sets  )  Finally,  transfer  ihi,'  $RA  fi!e  to  the 
SYSTEM/TtJOLS/  direchin'  on  the  Ixiot  disk.  After  luading  the  tmil  set  with 
LoacETcmh  or  LjOadOneTonl,  applications  can  use  it. 
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BEFEBENCE  SECTION 

Table  R3-1:    Tht  Majnr  Functions  cfihe  Tuul  Locator  Tool  Set  ($01) 


Function  Name 


GctFuncPlr 

CetTSPtr 

CetWAF 

LoanOneTool 

LoadTools 
SetTSPtr 

SelWAP 


Functifm 
Number 


$0B 


SOC 

$UF 

$t>E 
$0A 

$UD 


TLMounlVolnme  311 


Hlack 

Parameters 


Descriptian  of 
Faranteter 


result  (L) 

SysteoiOrUser  (W) 
FuncTSNum  {\V) 
result  (L) 

SysleinOrUscr  [W) 
TSNumber  (W) 
result  (U 

SysteniOrUser  (W) 
TSNumber  (W! 
TSNumber  (W) 
MiiiVcrsion  (W) 
ToolTabIc  (L) 
SystemOrUser 
TSNumber  (W) 
FPTptr  (L) 
SystemOrUser  [W] 
TSNumber  fW) 
WAPptj  (L) 
result  (W) 

WhereX  (W) 

WhereY  (VV) 

LinelFtr  (L) 
Line?2Ptr  (LJ 


ptr  to  fijnction  handler 

0  =  systeni/SSOOO  =  user 

function  (high)/lool  set  (low) 

ptr  to  ftinttion  pointer  table 

0  =  systL'ni/$8aO0  =  user 

tool  set  number 

ptr  It)  ttxjl  set  work  area 

0  =  system/$8000  =  user 

toril  set  number 

totil  set  number  to  load 

minimum  version  required 

ptr  to  too[  set  load  table 

0  -  system^$SO00  -  user 

tnol  set  number 

ptr  ta  funttion  pointer  table 

0  -  system/$8000  =  user 
too!  set  number 

ptr  to  work  area 

1  -  OK.  2  =  Cancel 
selected 

upp*?r  left-hand  X 
ctKJrdinate 

uppLT  lelt-bsnd  Y 
coordinate 

ptr  lo  string  at  top  of  Ikix 
ptr  to  string  below  line  2 
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Fiinctum  Stuck 
Function  \!0jne       Numher  Paruiiiirters 


Deacrifttion  of 
Fararni'ter 


TLShutDown  §03 
TLStartup  S02 
UnloadOiieTool  SIO 


ButtiiinlFtr  (U 
Butb(jii2Plr  (L! 
[no  p;irameters| 
\mi  parainetersl 
TSNiimber  (VV) 


ptr  Uj  text  for  OK  button 
ptr  lu  Ifxt  for  Cancfl  buHon 


too]  set  number  to  unload 


Table  Tnn|  t^otator  Error  Codes 
Error 

Ciifli-    Description  of  Error  Condition   

SOI  10  The  specified  tninimum  tool  set  ve^^il)n  was  nut  luund. 

NOTE:  LckuITlhjLs  LiDiii  LujiiUiii'TuuL  pan  also  return  PniDOFi  errflr  cudeit. 
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Listing  3-1:    Tlie  STANDARD,  ASM  Program  with  Standard  Tool  Start-up  and 
Shut-down  Seciueiices 


DcStartup  and  DoShutdown  ere  standard  apenjng 
and  cloaing  sequenc^^  for  moat  programa. 

Set  VidMode  and   KPIanCJamp  as  appropriate  for  the 
video  mode  ytju  're  using    (32  0x200   ar  GIOjiSOO). 

Alt   the  tools  referred  to  in  TdolTa-bie  mual  be  in 
the  SYSTEm/TOOLS/   direclDry.    If  you're  mi^aing  some, 
remoue  the  entry  from  ths  tabic,  ctiange  the  initial 
count  byte,   and  remove  the  Startup  and  S^utDoun  calls. 

DoStartup  START 

•  Direct  page  equates 


DeRefLoc 
DPAddresB 


&e;qu 

GEQU 


*  Gereral  equates: 


False 
True 

Vi  dhode 
Xna:iClflmp 


GEQU 

CiEQU 
GEQU 


10 

DeRefLoc*-! 


iSOOO 


too 

£40 


;LDNG  (used  for  dereferencing  handl 
i  INTEOER   {address  of  direct  page) 


iBoolean  fals^e 
iBaglean  true 

jiao  ■  G4O)(200,  (00  -  320x200 
;Video  width  (640  or  320) 


*  Paint  offsets: 


V 

OEQU 

0 

;Vertica]  position 

h 

GEQU 

2 

;JHorizorlal  pusition 

•  Rectarigl 

e  offset 

5  : 

t  op 

0 

left 

GEQU 

2 

bot  t  oib 

4 

r  ight 

GEOU 

& 

•  GetNevtE 

went  and 

Tas I  Mast  er 

result   c  ode^ : 

bl nDownEvt 

CEQU 

1 

iiTi'Oiise'dovin  event 

k  eyDowrEvt 

Geou 

3 

;  tey-do*n  euen  t 

an  t  cKeyEu  t 

GEQU 

IButo-liey  ewent 

Lipda  teEv  t 

GEQU 

e 

J  upda  t  e  even  t 

ac  1 1  lyg  teEv 

t  CEQU 

8 

; act  i  va te  even t 

wl  nf^enLiBar 

OEQU 

5  7 

i  i n  me nu  bar 

wlnCan  tent 

GEQU 

19 

;ln  conleTit   region  of  wirda 
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^  In  cloae  box 

;in  special   menu  item 


;  Oi B 1 J  t em  Type 

cades : 

ButlcTiItem  GFIQU 

1  0 

Check  Item  GEQU 

1  1 

1  a 

1  -C 

ScrgllBarltem  &EQU 

1  3 

Uief  CU  It  Pin  GEOU 

1  q 

StdlText  GEQU 

IS 

LongStatTexl  GEQU 

16 

EditLine  GEQU 

17 

IcDTiltem  GEQU 

18 

Picltem  GEQU 

19 

Uaer 1 tem  G^OU 

£0 

UscrCtl Items  GEQU 

21 

Ua  1  ng 

S  t  B  r  t  Da  t  a 

PHK 

PLB 

_TL5tart 

up 

_nTStBr  t 

up 

PHfl 

_MM5tar  t 

lip 

PopWord 

Ply  ID 

;Pata  bant  -  program  bainlL 

;Tool  Locator 
jMi'Scellaneoiia  Tool  a 

;5pBce  for  resuit 
; Memory  Manager 


1  Get  direct  page  memory  for  Iht  ta&l  seXtt 

;Spacc  for  handli 


PHft 
PHfl 

PinhLong  #1000 
PushWord  tlylD 
Pu^ihWord  #ICOaS 
PiiihLong  fO 
.NewHandle 
PopLang  DeRefLoc 

5TA  DPf^^ddr^q^ 

PLi^hWord  DPAddresa 
PuahWord  ^VidMode 
Pu^hUlord  '160 
PuahWord  MylD 
.ODStartup 


;Thirteen  pegea 

jlD   lag    to  use 

;Locked,  fixed,  aligned,  fixed  bank 
iBank  100 


;Dereference  the  handle 

;   and  save  the  pointer  flow) 

; DP  to  use   (3  pages } 
; Graph i c 5  mode 
; ma  X  width 
ilD  tag   to  uae 
;  Qu  i  c  k  Dravf   I  I 


_ 1 nl 1  Cur  aar 


jDlftplay  arrow  cursor 
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LDfl  DPAddre55 
CLC 

ADC  ,rs30  0 

PHA 

PushWord  '0 
PuahUord  *'0 
PushWord  /XMaxCUmp 

PushUord 
PuahUord  MylD 
.EMStartUp 


;onc  page 

;quBuc  size  (default) 
; X  mi n  for  c lamp 
;x  max  for  clamp 
1 y  min  fof  c lamp 
max  for  clamp 
; ID  tag  to  u9e 
[Event  Managsr 


*  How  load  the  BflM-hased  loola: 


GctTools 


Pu5hPlr  ToolTah-le 
LoadToo la 


Abor  t 


DMP 
BNE 

CMP 
BEa 

PLfl 
JMP 


Startnor-e 
Abort 

flabForDlak 
DetToD Is 


DoShutl 

;Start  jp  the  real  of  the  tool 
StartMore  flNQP 

_ODflijxS  t  a  rt  up 


jError  Wfl5  Vulum*  Hot  Fourd? 
; Kq ,  ao  branch 

lAalc   fpr  hoot  v/olume 
:  Ve5 ,   5P  b  ra  nch 

((remove  return  address) 


sets: 


iQjtickDraw  AuxHiary  Tools 


PushWord  MylD 
LDA  DPAddrasB 
CLC 

ADC  '$400 
PHfl 

_Ct iStar  tup 


; one  page 
;Contr{i][  Mafiager 


PushWord  HylO 
_UirdStartup 

PuahLong  »C 
_Ref reahDeaktop 


jUindaiw  Manager 
;Draw  the  screen 
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LDfl  DPflddreaa 
CLC 

ADC  tt^CQ 
PHft 

_l1t"nu5  t  a  r  t  up 


; 0 ne  psge 


PushUord  MylD 
CLC 

ASC  «t60O 
PHA 

_LESlarlup 


;L  L  neEd  I  t 


_Dia  1  ogS  1  ar  I  iip 


iDialog  Marager 


PuBhWord  MylD 
LDfl  DP^^ddress 
CLC 

ADC  i'»700 
PHA 
SFStartup 


;one  page 

^Standard  F4]e  Qpsralions 


DPAddreas 


LDA 

CLC 
ADC 
PHA 

_SoundS  tar  tup 


;one  page 
(Sound  Manager 


Insert    Ihis   lo  starl   up   the  Pri.nl  Manager: 


PuBhUcrd  MylD 
LDA  DPfldtfres5 
CLC 

ADC  '»9DC 

PHA 

_PMStflr  tup 


;  t wo   pa ^eS 
iPrinl  Manager 


PushWord  My[D 
LDA  DPAddrssa 
CLC 

ftDC  i'SBOa 
PHfl 

_FMStartup 


;Gnfr  page 
jFonl  rianager 
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LDfl 
CLC 
ADC 
PHA 

_SflNEStartup 


DPAddresa 
i'tCOO 


_IMStartup 
_Dpsl:gtartup 

GTS 

ftakForDis*  f^NDP 

..&ET_HDQT_VDL  OBVParma 
PHft 

PushWord  *150 
PuahWord  *50 
PuahPlr  Promptl 
PushPtr  yolNamt 
PushPlr  QiK_n5g 
PuihPtr  Caneel_M5g 
_TLMQun  t      1  Lime 
PLA 
RTS 


;one  page 
iNumerics    < SflHE ) 

;ScrBp  riBTvager 
; Integer  Math 
;De9k  nanac|er 


;Gtt  rame  of  boot  uoluma 
Vapace  for  result 


Pr  omp 1 1 

Vol Hame 


STR 
DS 

STR 

CancBl.Msg  STR 


'  Ingert  the  ualiiime:  ' 
18 


;5pace  for  volume  name 


I  Abort 


DoShutDouir  ENTPV 


_DeH  k  Shu  t Doun 

^IMShutDown 

_ScrflpShu  t  Down 

.SANEShutDown 

_ri15h(i  tDowr 

_PMShii  tDowr 

_SoLindSKLitDowin 

_SFShiitDowTi 

_DialogShLitDoun 

_LCShulDowTi 

_r'leniiShgt  Down 


iCatl   this  if  u?iTig  Prinl  nanagcr 
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^WirdShutDgwti 
.C 1 1  Shu  tDown 
QDfiuxShiitDown 


DoShutl 


ENTRY 


lEtiler*  here  if   LoadTools  fails 


_E"MSh  Lit  Down 

_QDShLil  Down 

Pii5hNDrd  MylD 

_MTShu  t  Down 
_TLShutDowr 

_Quit  QuilParms 

BRK  IFD 


-.{Shouldn't   get    this  far) 


END 


StarlData  DflTfi 


My  ID 


DS 


QLiitParms     DC  M'Oi 
DC  I2'0i 


;Rtturn  to  caller 
;  Nc-  s  pec  lal  flags 


Tabic  of  Hftn-b3  5pd  t&ols  to  load.  Duly  ioad  the  t{H}l5  ynu 
have    in   the  SYSTEM/TDOL  S  directory, 


Too  i  Tab  1  e 

DC 

1 

M  1  ' 

;NLimher  of   tools  to  load 

DC 

1 

'  1  A  ,  tOOOO ' 

;UiFdow  Manager 

DC 

1 

MS,*05D[)' 

iHenu  nafiag^er 

DC 

I 

'  16,tOQ00 ' 

;Cantral  Manager 

t 

DC 

1 

M7vtD00a  ' 

;  [System  Loader  always  loadGCl 

DC 

] 

'  IB.SOQOO • 

;0ukcl(Orau  Aux  Tools 

■1 

DC 

J 

i 19.10000' 

;Prirt  Manager 

DC 

I 

•20  ,SQOCD' 

1 L i ne  Edit 

D£ 

1 

'21  ,10000' 

;Dialog  Manager 

DC 

[ 

'22,10000' 

;Scrap  Manager 

DC 

I 

' 23 , SOOOO ' 

;5tandard  File  Dperat^on^ 

I 

DC 

I 

'24,*OOO0' 

■,axsk  utilities 

DC 

I 

;Note  Synthesizer 

■ 

DC 

I 

' 2G, tODOO ' 

iHote  Sequencer 

DC 

1 

'27  ,1  00  00  ' 

iFcnt  Manager 

DC 

I 

'2S,tQa00i 

;Liat  Manager 

EMU 
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Listing  3-2:      A  User-dffincd  Tool  Set 


*  This  program  shows  what  a  iu^tam  tool    set  * 

*  looLi  like.   The  fir^t  pgrtion  inatalls  « 

*  the  tool    set    into  the  lastr   tool    aet   table.  • 


KEEP 
MCDP-r 

TS_Nuw  &e:qu 

UserDrSys  GEflU 
Installer  STAIST 


TDDLSET 
TOOLSET. MflG 

$01 

$80  00 


1  Tool    5et  number 

;  13000   =  user   tool  set 


_TLStor tup 
_TextStartup 

;   This  code  inatalli^  the  u^er   tool  set: 


PuahUord  'UaerDrSys 
PiishWord  'TS_NUW 
PuahPtr  ToDlSet 
_SetTSPtr 


iTool    Set  type 
iTool   3et  number 
iPci-nter    to  FPT 
{Install   the  tool  set 


;    How  let's   teal    the    tool    5et   by  showing  the  day  ef    the  week: 


PushPtr  TheBuffer 
LDJ(  *TS_NUM+9-2E6 
JSL  tElODOa 

Pu5hPtr  TheBuf-fer 
_Wr-  1  leS  t  r  1  ng 

_Tb  » IShu  t  Down 
_TLShutDQwri 


iCall   DayOfWeelc  function 
;*E:iOO0S  -  uaer  dispatcher 


;Dlsplay  on    text  screen 
ifthia  removEs  user  tool  set^) 


_auiT 

Quit  Parma 

BRK 

(FQ 

Qu 1 tParms 

DC 

14"  01 

DC 

1  2  ■  0  ■ 

TheBuf f er 

DS     1  Q 

!  Day 

END 

»  The  tofll 

■set  deflnitior  begiTia  here: 

ToDlSet 

START 

iDay  rame  retiirned  here 
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This   IS  the  fufictior  painler   table.    It  caritaiTis  the  addres^t'B, 
minus  1,  of  each  furction  subroutine.    It  begihs  uiith  a  long 
^MQril  eortflirlng  the  number  of  functions,  plus  1. 


OC  [.flf  {TBL_END-TDDlSBt  }/■!' 

PC  M 'TTBoot Init-1 ' 

DC  M'TTStai-tiip't  ' 

DC  ]4'TTSh(jtDpw>i-1  ' 

DC  M'TTVer5ion-1  ' 

DC  I1'TTResct-1 ' 

DC  M'TTSlatu9-1  ' 

DC  H ' Reaerved-I ' 

DC  M'fie5erved-1  ' 

UC  l-l'DayOfWeElt-l  ■ 


;Hiimber   of    functiona  ['I) 


TBL.END 


flNDP 


TTBootlnil  LDA 
CLE 

STL 


-0 


(Hall  errtJr  code 
;Na  error 


;TT5tflrtup  has  one   input   parame t er : 
;  address   m  hunt    tOO  af  a  one-page 
;   thi5  ward        buried  $07  bytes  iTito  the 
;   3-byte  return  addre^se?,    Dn  exit,  this 
i   parametitr'   from   the  stack   by  ifl&ving  the 
;    stack    pointer   Lip  by   two  bytes. 


a  word  representing  a  starting 
wark   ares,  entry  to-  TTStartup, 

stack,    ju5l  above  the  two 
furction  removes  the  irptit 
two  return  qiddreaaes  and  the 


TTStartup  ANDP 
LDfl 


*07,S 


jGet  direct  page  address 


PushWord  l'U5er0rSya 
PuahUordi  fTS_NUn 
PushWord 
PHfl 
SetUAP 


jTool    set  type 
;  To  0 1   5,e  t  number 
^High  luord  of  address 
;Low  word  of  address 


Remove  the   input  parameter  from  the  stack: 


LDft 

STfl 

LDS 

3.5 

ETA 

s.s 

LDA 

1  .s 

5TA 

TSC 

CLC 

ADC 

TCS 

Plove  the  two  long  JSL 
return  aduJreas  up  by 
two  byte5 


1  Increment   the  SP  by 
;    two  bytea. 

ViCould  juiit  do  PLA  instead) 
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CLC 
RTL 


«0 


;  Ex  i  t  wi Ih  na  error 


;To  shutdown   this   tool    sat.    j  u^it    zero   the  ertry   iti  the 

;    MQrk    arcq   pi^inter    table.    It    IS    ufl    la    the   SppllcatiGfi  to 

;  dispose  of    the  area  it  points  to  {1191119  Di  sposeH^Tidl . 

TTShutDowr  ANDP 


PushWord  'UserDrSya 
PushWord  'TS.NUM 
PushLprig 
SetUAP 


1T00I  5el 
jToal  set 
:flddreaa  is 


type 
niiUiibBr 


LUfl 
CLC 
RTL 


'0 


TTVerslon  returns  o  version  ward  In  o  apace  on  the 
^tack    -aliijcaled    by    the    caller.    The   high'order  byte 
contains   the  main  version  number  and  the  Itjw-order 
byte  containa   the  secondary  version  nurtibpr.  The 
stack   resLilt  Space  begins  at  an  offset  of  from 
SP  because  there  are  two  3-byle  return  address  on 
the   top  of   the  stack   on  entry  to  TTVerslon. 


TTVersion  flNQP 


LDA 
STA 

LDA 
CLC 
RTL 


J07,5 
*0 


• Ver  5 1  on    ?  .  1 

;Put   result   in  stoct  space 


TTReset 


LDA 
CLC 
RTL 


'D 


TTS  ta  1 115  rptitrh5 
reserved 
liQ5  been 
has  bean 


a  Boolean  f^ord]    in  the  stack  space 
by  the  caller.    The    result    is   true   if  TTSlar  tup 
caJlcdi  -false  otherwise,  TTStalus  fcTiows   if  it 
called  hecause  the  WflPT  entry  will  be  nonzero. 


TTStatus 


ANDP 


BEQ  SetStatus 


i  l5  WflP   (  low)  zero'' 
;Ye5  ,    50  itore  false 


LDA 


;True  code 
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SelSlatuis  STfl 


t07  ,S 


;PllI   result    in  atacfc  space 


Reserved 


LDfi 
CLC 
RTL 

LDA 
EEC 
ftJL 


#TS  HUM'2&G-tSrF      ^Efror   JFF  meaFi5    "nut  impiemtntad 


•  The  DayQfkleel  fiinction  expecla  ore  parameter-  on  the  stacks  a 
<  fjoinle-'    Ifl  a  data  area  uhert   the  function   is  to  return  the 

»  day-of-weet   string.   Not*   that  alter  the  initial  PHD  ansJ 

•  aligning   tht   new  direct   page  with  the  atacfc,    th*  poijittf 


<   1 5  at 

DayOf  Uleek  AHQP 

OldDP 

EQU 

*01 

RTLl 

EQU 

QldDP*? 

RTL  2 

EOU 

PTL1 *3 

ThePlr 

EQU 

l?TL?-t3 

PHD 

TSC 

tCD 

PHA 

PHA 

PHfl 

PHA 

_ReadT 

1 meH  e» 

PLfl 

PLfl 

PLfi 

PLA 

XBA 

AND 

DEC 

A 

CMP 

^7 

BCS 

DDU^Ef  ror 

;  Save  current   direct  page 
;A1  igri  d.p.   with  slack 

;Space  for  S  bytes    of  result 


;  Pop  miTiate/second 

■,Pop  year/hour 

iPop  month/dBy 

;Pap  day  of  "eelc    [high  byte) 

■,pLit   da/  q"*   week    in   low  byte 

iStrip  unuaed  blt^ 

;  COTiver  I   t..7   lo   D..G  (l-Sunday) 

; 'N Limb er    jr  range  (O.-B]' 
;  No  ,    ao  Branch 


J   Look   for    the  Nth  entry   in   the  table; 


TAY 

FindEntry  CPV 


EaveReaui  t 


■,At  correct  nariie'' 
iYe5,   SO  branch 
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FE2 


INX 
BRA 

INX 

DEV 
BRA 


>DoyTablB ,X 

TEE 

FE1 


1  ndEn  t 

;    Transfer    the   name   Ic  the  buffer  area: 


;(rcirce   long  because  B'>K) 
;Drarch   if  at   end  ai  name 
i Move  to  next  character 


lHove   to  atart   of   next  name 
;Decrement  dsy  ~a'f -j/ssk  counter 


Saueftes  u 1 1 

SEP 

»»20 

;U3t  a-bit  accumulator 

LDNGfl 

Off 

LDV 

/I 

SH1 

LDfl 

>DayTflble, t 

BEQ 

SR2 

jBranch   if  at   end  of  name 

STfl 

[ThePtr] .V 

INX 

:m 

Bftfi 

ER1 

SR? 

DEY 

TYA 

STfl 

[ThePlr] 

sStare   length  of  string 

REP 

iBacfc   to  16-bLt  acciimulator 

DN 

LDA 

*0 

; No  error 

SRiP 

DOW_Exit 

DOW_Error 

LDA 

'TS_NUri«25e*»D1 

;Error    code  f1 

DDW_Ex 1 t 

TAX 

iSawe  err&r   tode    in  X 

PLD 

^Regtore  direct  page 

;   Ref!(Du-e   the  Icng 

irput  parameter' 

from   the  stac  1;  : 

LDA 

5.S 

jMove  the  two   long  JSL 

ETA 

3,5 

;    retuf-Fi  address  up  by 

LDA 

3.S 

;   four  bytes 

STfl 

7.S 

LDfl 

I  .s 

STA 

5,5 

TSC 

; I ncr  ement    t  he  SP  by 

CLC 

!    four  bytes. 

ADC 

TCS 
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CnP  *1  i^*"-  carry    if  eiTor 

RTL 

MSB  OFF 

DayTflble       DC  C'Stjnday'  .I2'0' 

DC  C  'Monday '  ,  12  '  a ' 

DC  C'Tuesday'  ,]Z'<i' 

DC  C 'Wednesday ' , 12' 0 ' 

DC  C'Thursday'  .12'0' 

DC  C'fridflj/'  .I2'0' 

DC  C'Salurday' , 12' 0' 

END 
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CHAPTER  4 


Memory 
Management 


As  discussed  in  chapter  £,  the  658  Ifi  inicrnprotessur  that  t;ontrols  the  GS  can  access 
directly  an  eiuirnnius  Ib-inegabyte  uiemf>r>  spact;  (arranged  as  256  memory  hanks 
of  64K  each),  the  24-bit  memon-  addres.sL-^  run  IrDni  $000000  to  $FFFFFF,  This 
space  can  be  made  up  of  any  combination  nf  ROM,  RAM,  and  memory- mapped  I/O 
(soft  swittb)  loeatioijs.  but  It  need  not  he  hilly  populated,  [n  a  coinpntcr  system, 
the  ROM  holds  a  bare-bones  operating-system  pros^'ii  (somctim{'s  called  a  system 
monitor]  which  loads  a  more  elaborate  operalins  system  from  disk  when  the  system 
is  turned  on,  It  also  usually  ttmtains  a  coileetioii  of  subroutines  that  an  appliciJtion 
program  can  call  In  perform  sliindaid  tasks,  sudl  us  c-lennng  the  screen,  reading  the 
keyboard,  and  printing  a  character.  RAM,  of  Murse,  is  where  an  application  stored 
on  disk  is  loaded  mid  where  data  of  any  sort  can  be  stored  by  an  application  or  the 
operating  system. 

This  chapter  inveKti^atcs  the  jjpeciaL  uses  the  GS  makes  of  the  meniory  in  the 
6581()'s  address  spaL-e.  Sunie  clues  eoiiceming  the  nperation  ol  the  GS  will  be 
uncovered,  and  you  will  discover  whicb  areas  of  IL^M  are  avadable  for  use  by  your 
own  appUcationS. 

When  writinf^  an  application  for  the  cs  (or  any  computer  for  (hat  matter),  it  is 
important  to  avoid  nsing  memory  areas  already  in  use  by  the  operating  system  or 
by  any  other  application.  If  yon  overwrite  busy  memory  areas,  the  system  is  sure 
to  behave  unpredictably. 

It  is  easy  to  write  a  prn^ram  fur  the  He  that  does  not  conflict  with  the  original 
FroDOS  8  operating  system.  FiuDUS  8  occupies  specific  memory  areas  and  pro- 
grammers are  responsible  ennuKh  nut  to  use  those  areas  for  applications.  Trying  to 
hve  with  another  application  in  memor>',  such  as  a  desli  aceesSorv  utilit>'.  can  be 
fatal,  however.  Why?  Because  no  software  protocol  for  infnrminf;  an  application  of 
the  iJiemorv'  other  applications  are  oct:upyin.g  has  been  implemented,  A  co-resident 
desk  at;cessor>'  utdity.  Such  as  the  Pinpoint  Desk  Accessories,  is  useful  only  because 
it  occupies  an  area  few  applications  use  (the  auxiliary  bank-switched  BAM  area). 
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A  proErani  can  avnitS  rnfTTiDrv  conflicts  in  ;i  PrciDOS  16  r.s  rnvironTnc-nt  simply 
by  ujsind  a  ttxil  set  faJkd  the  .Memory'  Miiiia^tr.  Whi-n  the  pni^ram  iict'Ji  a  block 
of  memiHT'  ta  wiirk  with,  it  simply  issues  a  request  to  the  Mf  mary  Manager.  Tlie 
Memorj'  Manu^t^r  prOLt  iSL-s  the  request  by  locating  a  frt'C  a,rpa  of  memory  of  the 
prnpi-r  siziL".  markin;;  it  iis  in  use,  and  returning  its  handle  [the'  address  of  a  ptiinter 
t!j  it).  As  long  as  every-  program  uses  the  Memory  Manager,  no  program  will  tread 
on  the  toes  of  any  other  program. 

The  use  of  the  Memory  Manager  is  discussed  at  the  end  of  this  ciKapter. 

cs  MEMORY  MAP 

As  shown  in  figure  4-1.  the  t:s  can  address  up  to  256  hankii  ofmemorv'.  The  banks 
are  numhered  frcm  $t)0  to  $FF,  and  each  one  is  G4K  in  size.  In  its  mintnisl 
tonfigiiration  (no  esrd  in  the  memory  expansion  slot},  the  CS  ha.*;  25fiK  nf  BAM  and 
12HK  nf  ROM,  sn  it  usx-v  cmly  six  of  these  hanks:  hanks  SOO.  SOI,  SFO,  SEl,  SFE. 
and  SPF-  Thr  first  four  nf  these  hankh  hold  the  RAM.  ;ind  banks  SFF-  and  $FF  hold 
the  RflVI.  Thr  rat  ctf  the  banks  are  unoccupied  or  unavaitahle. 

The  R.^M  in  hanks  SEO  and  SEl  desert-es  special  mejitioii  because  it  has  one 
rr.slrictivc  diaracterisEic  that  the  RAM  in  other  banks  does  not:  r^ad  and  write 
operations  affcctinn  these  banks  al\^'iiya  take  place  at  the  normal  (T  MHz)  dncfe 
^peed.  ev  en  if  the  system  Speed  is  set  to  fast  i'l.fi  MHz), 

Ef  you  are  operatinji  in  fast  mode  and  you  start  usiiip  either  of  these  banks,  the 
C;s  hardware  slowA  the  system  down  and  automatically  returns  to  fast  mode  when 
you  aj-e  done,  The  reason  fur  the  slowdown  is  that  bank^  ^iF,n  and  $E1  contain  video 
display  buffers  and  other  memory- mapped  I/O  locations  that  for  reasons  of  com- 
[jatiliilih,  with  existing  lie  software  and  hardware,  must  he  accessed  at  the  same 
clock  speed  used  by  the  lie  (1  Mflz), 

You  can  add  more  R.AM  to  the  cs  by  inserting  an  appropriate  card  in  the  memory 
expansion  slot  (see  appendix  fil,  Additional  FLAM  occupies  consecutive  hanks  begin- 
ning at  bank  $02 — if  you  add  one  niejiah)  te  of  memory  (sixteen  banks),  for 
example,  it  will  occupy  banks  S02  through  S 1 1.  The  upper  hmit  for  ItAM  expansion 
through  the  ineinor\'  expansion  slot     8  megabytes. 

A  memor>'  expansion  card  may  aho  contain  ROM.  The  ROM  may  occupy  any  of 
the  lianks  from  $F(i  to  SFD.  The  data  in  banks  ftFO  to  SFT  {a  512K  space)  is  expected 
to  be  oryani?od  just  it  would  he  cm  a  disk:  thiit  is,  these  HOM  hanks  are  configured 
as  a  ROM  Di'^k-  Tlie  ROM  to  banks  ^FH  to  ^VD  is  designed  to  hold  extensions  to 
the  firmware  ROM. 

SPECIAL  RAM  AREAS 

Several  areas  in  the  four  cxjre  R,\M  hanks.  (WO,  SOI,  *t]0,  and  $Ei)  are  vised  for 
special  purposes,  hy  the  6iD816,  the  Operating  system,  the  firmware,  or  I/O  devices. 
Prot^ranis  must  respect  this  usage  and  not  attempt  to  use  these  areas  for  other 
purjJosesH  exeept  where  tlie  context  permits. 
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Figure  4-L.    T[lo  hpph  llr:s  Mcmor>-  Map  [Each  K\M  hank  is  &4K  in  size.) 


bank -J  $00 


$01 


$02  S7F 


Main/Au>(niary 

RAn  ror  i  ie/iic 
Applications 

(128K) 


Expansion 
RAM 

(to  a  megabytes)  \ 


RAM 


$E0 


$E1 


System,  I/O, 
and  Video 
RAH 
C128K) 


b.nk  -*_SFO  ...^SFT^  ^  ....  $FD 


Ron  Disk 
Memory 
[5 1  2K) 


System  ROM 
Expansion 

(384K) 


$FE 


$FF 


System 
(12aKJ 


ROM 


Special  H^M  An-ws 


Banli^  SEO  and  $EI 

The  two  li.\M  l>unk»  in  the  hiEh  end  of  menion',  banks  $E0  and  $E1.  arc  often 
referred  In  as  the  jfirtnuvirf'  RAM  beciiiise  ihe  ROM  drivers  for  peripheral  ck'viciJ^, 
such  as  the  serial  pnrts,  the  mouse,  and  the  disk,  use  thfsf  banks  for  data  stcragf. 
Tlie  System  Luader  (the  portion  oi  the  operating  system  thot  loads  ProD<)S  16 
applications).  AppleTalk.  aiul  tool  sets  also  make  cvtensivp  use  uf  the  firmware 
RAM,  As  mentioned  earlier,  reads  and  writes  tt>  banks  $E0/SE1  aJways  take  ^ilaee 
at  I  MHz,  even  if  the  tiystcm  clock  speed  is  set  tu  2.^  MHz. 

Tlie  arrangement  and  usv  of  int'nit)r>  in  firmwaj  e  RAM  on  the  CS  is,  in  many 
respects,  the  same  as  on  the  He.  Bank  £E0  looks  moth  like  main  memory  on  the 
llf  ^nd  bank  $E1  looks  much  like  auKiliary  memory'.  The  similarities  are  reviewed 
below. 

Languag,e  Card.  The  space  from  SDOOO  to  -SFFFF  (12K  in  size)  in  either  of  the 
two  banks  of  firmware  RAM  is  called  ii  lanf^iiircti^e  card  (or  ban k-s witched  R,\M)  and 
can  be  a.ssofiated  with  cither  I2K  of  llOM  ot  16K.  ofllAM.  A  program  can  switch 
between  ROM  ami  RAM  on  the  fly  by  man  isolating  a  set  of  safb^'are-contrQUable 
switches  (called  sufl  switches), 

The  ROM  for  the  language  card  is  actually  physicalJy  located  in  hank  $FF  (al  the 
same  relative  position  within  the  bank),  but  this  area  also  maps  to  banks  SEO  and 
SEl  when  the  cs  i^  tunied  on.  The  ROM  contains  Applesoft,  the  system  monitor, 
I/O  drivers,  toot  sets,  and  more. 

The  RAM  for  the  language  card  actually  takes  up  4K  more  space  than  what  is 
available!  The  extra  4K  is  treated  as  a  second  $D00O-$DFFF  mcmorj-  segment  and 
soft  switches  are  available  to  select  which  of  these  two  banks  is  to  be  active.  On  the 
GS,  the  language  c;ird  RAM  in  banks  ^EO^SEl  is  reserved  for  use  by  the  ProDOS 
System  Loader  and  by  ApplcTalk. 

I/O  Space.  The  I/O  space  runs  from  SCOOO  to  *CFFF.  The  first  part  <jf  it,  frtjm 
SCfXiO  to  SCOFF,  is  actually  made  up  of  memory- mapped  I/O  Ineatinn'; — that  is. 
locations  that  can  be  read  frani  or  written  to  so  th*t  you  can  commnnieatf  with  I/O 
devices.  Each  slot  [or  built-in  port)  ha.';  the  cjiclnsjve  use  of  sixteen  unique  1/(3 
locations:  SCOOn-SCOSF  for  slot  1.  SC:DAO-SCnAF  for  slot  2,  and  so  on  up  Ui  $COFU- 
$t:OFF  for  slt>t  7.  The  I/O  locations  frctm  SC()(X)  to  SC07F  control  internal  I/O 
devices  (such  as  the  keyboard  and  the  video)  and  modes  of  operatio]i  (including 
memory  selection,  system  speed,  and  graphics  mcjdf  selection]. 

Peripheral  ROM.  Tlie  lotaticins  from  $Cn004CnFF  (n=I  to  7)  arc  reserved  for 
ROM  foinid  on  a  penpherd  card  plugged  into  slot  n.  {Intenial  port.s  have  ROM 
associated  with  them,  tno.  It  is  stored  in  the  Inwer  part  of  bank  SFF  but  is  also 
mapped  to  (he  SC^nxx  pages  in  banks  SEO  and  SEI.}  A  typical  ROM  contains  a 
program  that  provides  the  subrontnies  a  pr^i^ram  needs  to  cunimunicate  easily  with 
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a  periphenil  device.  Each  periplicriil  may  also  contain  a  2K  ROM  area  that  occupies 
$C800-SCFFF;  the  peripheral  can  select  this  ROM  area  to  the  exclusion  of  all 
otliers- 

While  a  prajiirain  is  running  in  the  peripheral  Ri^M  area,  the  GS  aJwavs  operates 
at  normal  speed  [1  Mliz).  This  is  done  to  permit  fimiiig-seii.sitivtf  peripherals 
designed  for  the  lie  to  work  pmperly  on  the  cs.  For  example,  an  intemjil  modem 
card  like  the  Hayes  MieromcidL-m  w-ill  not  wurk  at  a  cl  ick  speed  nther  than  L  MHz 
because  the  prOKrain  in  its  ROM  that  dials  the  telephone  uses  precise  timing  loops 
that  are  based  on  a  I  NEHz  clodt  speed- 
Video  Buffem.  The  video  buffers  for  tlic  standard  lie  video  display  modes — 40- 
and  SO-colunin  text,  sinjile-  and  double-wdth  low -resolution  and  high -resolution 
graphics — ar--'  located  in  the  same  relative  positions  on  the  CS  as  on  the  lie; 

S4t)0-S7FF  are  ustd  fi>r  the  pajjje  1  40-i:oluinn  text  display  and  iHw-resolution 
graphics  modrs 

$800-$BFF  are  used  for  the  page  2  40-column  text  display  and  low-resolution 
graphics  modes 

S2000-$3FFF  are  used  for  the  page  I  high-resolution  graphics  mode 
S4000-S3FFF  are  uieJ  for  the  page  2  hi|i;h -resolution  graphics  mode 

In  each  tase.  the  standard  text  and  graphics  modes  (40-i^nIiimn  test  and  sinsle-w-idth 
graphics)  use  areas  in  liank  ?Efl  only  For  SU-column  test  and  double-width  graphics 
modes,  the  same  areas  m  bank  $E1  are  also  used 

Other  Special  Areas.  Another  display  mode,  called  super  high -resolution  graphics, 
has  a  video  buffer  located  from  S2000  to  S9FFF  in  bank  SEl  only.  This  is  the  display 
buffer  used  by  the  QuickDraw  II  graphic  drawmg  tool  set  that  is  stored  in  the  GS 
ROM,  It  does  not  exist  on  the  He 

The  other  areas  in  banks  SEO  and  SEl  that  have  special  significanLe  are  the 
spaces  from  $(XK)0  to  SIFFF  in  both  banks  (which  include  the  video  huflers  from 
$400  to  SBFF  llsat  were  di;ieussedl.  These  spaces  are  reserved  by  the  operating 
system  for  the  storage  of  variahles,  vectors,  jump  tables,  and  other  data  used  by  the 
GS  tools  and  built-in  1/0  ports. 

Free  Areax.     Tlie  areas  in  banks  SEO/SEI  not  used  for  special  purposes  are; 

•  S6000-$BFFF  in  bank  SEO 
■  $A(X>0-SBFFF  in  bank  $E1 
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These  areas  are  free  for  allocalion  b>'  rhe  ML'iTiOf>-  Manager.  Keep  in  mind  thai  for 
all  practical  purpo^trs.  tlie  video  hiiffrrs  u^ed  hv  pa>;.-  1  and  page  1  of  Kt^jiidard  hieli- 
resnliition  jiraphics  (.S2f)00-S.^FFF  in  hank  $E0)  are  u|.o  available  if  proRram  uses 
only  the  super  high  resolution  graphics  mode. 

Banks  $00  and  $01 

Bank  SIX)  is  of  particular  importance,  heeansc  this  \^  where  the  f>58[f>  locates  Ik 
stack  and  direct  paj;f.  In  eninlatiun  mode,  the  stack  oeoupies  pa^c  $0]  and  the 
direct  page  (iccypies  psRe  -SOO,  In  native  mode,  however,  the  nperatinfi  system  can 
pt>sition  the  stack  and  direct  page  anv-where  in  bank  $00, 

One  ol  the  priman-  clesi^;i]  constraints  for  the  Cii  w^vs  that  it  work  properly  with 
existing  He  software  fand  hardware).  To  all.iw  this,  it  was  neccssan  tn  permit  the 
remapping  of  banks  «00  and  $0|  so  t!iat  (hoiie  are;is  Liniid  he  umxI  as  the  main  and 
aii.vihar>'  int^mury  area.s  are  on  the  IJe,  complete  with  an  I/O  space  and  a  lan^^uage 
card  area.  At  the  same  time,  I/O  and  vid*^  operations  had  to  lak^-  pJtae  at  the  same 
cloeJi  speed  as  the  lie,  namely  1  MHz. 

One  way  to  acHjmplish  this  niifiht  h;ive  been  to  force  lianks  .'^OO  and  .$01  (o 
operatf  at  1  MHz  all  the  time  ^nd  to  keep  the  standard  video  huffer.  and  memory- 
mapped  I/O  locations  ill  (hose  b^nks,  This  would  mean,  however,  thai  one  espeeially 
eoinmiin  65816  operation— pushing  data  on  the  stack  [a  bank  *fX)  operation)— would 
always  cause  the  system  tosJowdown.  severely  restrictinj^  the  advantase  of  nperating 
the  CS  in  65SI6  native  mode  at  2,8  MHz 

The  iilthiiatc  M)lutioTi  wa,s  not  to  restrict  the  s^txA  of  hank  $00  and  SOI  operations 
to  1  VlHy  Rather,  the  system  was  desisned  to  detect  automaUcallv  a  write  operalion 
tn  a  video  butter  or  the  I/O  ..pace  (at  a  speed  of  2.8  \\\\,_  or  ]  MHz)  and  to  ecuerate 
a  rancurrent  write  operation  (always  at  I  MHzl  !o  the  .^ame  location  in  hank  SEO 
(fcjr  bank  .SOO  writer)  or  bjink  $EI  (for  hank  SOI  writes).  This  technique  i..  called 
shadov.\n^.  Reading  from  a  shadowed  video  buffer  docs  not  eaus.-  the  system  tn 
slow  down  beenusc  neilher  bank  iEO  nor  Iiank  $E1  is  aeecs.sed. 

The  areas  in  banks  S(H»  urid  $01  that  may  be  shadowed  are  ^howii  in  figure  4^2. 
The  CS  ha^^  a  lihuduw  rcf-iiter  that  wiltrok  which  video  bufrer>i  are  aetually  shadowed 
at  any  given  time  (see  figure  4^-31  .\  bit  in  the  ..hadow  register  also  L.tntrols  the 
shaciowin^  of  I/O  locations  and  language  c^d  operation. 

Notice  that  llie  page  1  te-tl  iu.d  Inw-resoliition  graphies  sere^-ii  tannut  |.e  shadowed 
using  hardware  tcthni<|iie...  but  it  is  rarely  used  anvwav.  [A  software  technitme 
u'Kerein  data  in  bank  m>/m  is  transferred  to  hank  SKO/SEI  m  response  to  a  periodic 
interrupt  can  be  itnpleimnled  to  emuIaH^  hardware  shadowing.  Invoke  this  bv 
.setting  Alternate  IJispkiy  Mode  (Jn  from  the  desk  accessory  inenu.) 

If  shadowing  is  inhibiled,  a  program  must  directtv  aceess' the  video  buffers  or  I/O 
locations  in  bank  *E0  or         Lnabliug  I/O  shadowing  also  creates  a  language  card 
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Figure  4-2.     The  Shadowed  Meiimry  Area^  on  the  Apple  llC5 
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NOTK;  Test  page  2  (SSOO-SBKF)  is  shaduwed  using  ioFtwjm-  let-bnir|i!i^s  if  Allf  rnaH-  Pispl^r  M:.df  is.  On. 


Lit  .fiDnnO-SFFFF  in  banks  $00/801  that  works  just  as  the  iHie  in  the  lie;  does  [see 
the  description  ahovc  fur  hank.  SEO/SEil-  This,  in  turn,  enables  access  trt  the 

Applesoft  and  sv-steni  nionitcir  ROMs-  ,    ,       ,        i.  n 

!n  normal  Appte  Mr  cmiilation  m<icle,  all  video  areas  are  ahadQ>veil  so  that  all 
existins  .^nlVware  will  work  properly.  Whtn  the  c;^^  s  nc^v  super  high-resolubon 
graphics  mode  is  used,  shadowioR  of  other  ^aphics  modes  is  disabled  so  that  the 
shadowed  space  in  banks  SEO  tan  bf  freed- 


Figure  4-3.     Thtt  Sliiidt™  Rpgistt^r 
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NOTE  Bil  A  wcrks  m  Lvitijuntliun  with  bits  I  and  2   If  (ji!  I  is  i-kar.  the  space  rrciirt  S2000-S,'iFFF  in 
Wlk  m  l^  sli,i.i„«.y.-[l  I..  Iwrtk  -JliO.  iJ  }«[  ^  i^  iiUn  tlc-jr,  llif  siinit-  Miat'-  ill  kink  *(Jl  1^  nl«>  iiiadtiwd  {hi 
ly^nk  SKll.  SuTiilji-ly,  il  Ihil  2  ,^  uli-iir,  ^'Ir^nnK  bit  4  Kimhtt-s  shailnwnig  frxjni  iW0OO-,'B5rFF  in  haiil<  »1 
(Iti  bank  »EH  f.^  «',.||  a.t        sanip  lacBtjnns  Jn  liank  SOO  (Id  Ijanlc  SEO). 


Ill  normal  operiitinn.  the  tiy  always  enable.^  shadowing  of  the  text  pages,  even  if  the 
test  si.Tet.-n  is  not  n'.rd.  Tlii.s  is  neceAsan-  so  [hat  He -^tyle  ijeripht-ral  cards  (which 
wi-ile  tu  nniised  Jiicas  of  tht-  text  display  huHerl  will  work  properly.  Also.  I/O 
shjdowini:  is  eiiahkd  so  thai  mh-rruptsi  (whith  vettnr  thmugli  ROM  in  bank  $00) 
can  be  handled, 


EXPANSION  RAM 

Banks  S02  thrnngh  ^DF  fl4  mcsahytes  le^s  art^  all  r<^ser\-ecl  For  future  RAM 

expansion,  althrnipli  Appk-  has  iin|xised  n  practital  limit  of  S  ine^jahvtes  by  not 
providing  dt-etfding  tirt'iiitr>'  l>eyoiid  the  S-im-Rahyte  limit.  Any  espansion  RAM  you 
adt!  is  available  liir  allot-ation  wilh  the  Memon'  Manager. 
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Figure  4-4.    The  CYA  ("Configure  Your  Apple")  Register 


7 

6 

5 

4 

3 

2 

1 

0 

SEOG036 


disk  motor-on  detect 
for  slots  7,  6,  5,  4 

1  =  permit  shadowing  in 
all  expansion  RAH 
banks 

0  =  no  such  shadowing 

1  ^  fast  speed  (2,6  mz) 
0  =  normal  speed  (1  hHz) 


Vidcd  and  1/0  ^haduwing  can  he  pf  rmittrd  for  ill  of  these  banks  as  a  group  fliut 
not  individually)  ljy  setting  a  bit  in  the  (JYA  register  [see  figure  4—1).  Even-nam- 
bered  hanks  sha,duw  to  page  SEO  and  ndd-numbt^red  banks  to  page  $El.  However, 
you  sh^jiild  ne\'L'r  shadow  expansinn  R.-\M  d'  ymi  are  running  CS-styk  applications 
becaustf  they  will  nut  run  properly.  Thf  proldeina  begin  when  the  Mcmtiry  ManiiRer 
idUjL'iiteii  spaue  iomewhere  in  (be  kngua^e  eard  area  of  a  bank,  an  area  where  ROM 
is  usually  enabled  Qust  as  it  is  in  hanks  3iO0/S01).  When  a  tool  or  a  program  tries  lo 
write  to  the  allociited  space,  iinthinn  is  saved! 

Refer  to  appendix  6  for  descriptions  of  several  meniory'  expansion  cards  available 
Ibr  the  cs. 

THE  ROM  BANKS 

Tlie  128K  ROM  in  banks  $FE  and  SFF  contains  the  ROM  versions  of  many  of  the 
GS  tnn!  spts  and  desk  aeeesson'  support  trode.  It  aJsti  contains,  from  to  $FFFF 

in  bank  SFF,  a  ."iyKtem  monitor  tomparablc  to  that  found  On  the  lie.  the  Applesoft 
BASIC  programming  lanjfuage,  and  subroutines  to  support  tlie  bnilt-in  peripheral 
devices  on  the  cs.  By  using  elever  hardware  remapping  teelmiques,  the  upper  12K 
of  bank  $FF  can  be  used  as  if  it  occupied  the  same  portion  of  bank  $E0,  $Ei,  or 
any  other  bank  for  whcch  I/O  shadowing  is  enabled. 
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Tlif  fciurtepii  banks  from  $F()  tn  SFD  art-  rp-^cned  for  fiiture  ROM  expansion. 
Banks  $F0  through  SF7  i^VZK}  are  ia  he  used  us  a  ROM  dkk  und  banks  SF8  through 
SFD  (3S4K)  are  for  additimiii]  firmware  ROM. 


THE  MEMORY  MAXACER 

The  Memory  Manager  is  tool  set  #2.  The  main  chore  it  performs  is  allocating  areas 
(jf  ineniory  in  .^uch  n  way  that  previously  allofiiltd  areas  are  not  diiturbed.  Jts  uther 
major  chore  is  releasing  dllixated  areas  of  memory  to  the  general  pool  ol  available 
memory. 

The  Memorv'  Manager  manages  all  uf  RAM  memory  except  the  fnlEowinR  areas; 

•  SCOOO-$FFFF  in  hanlcs  $()0.  $01.  iSEO,  SEl 

•  SOOO()-307FF  m  hanks  $00,  $01 

•  $0000-SlFFF  in  bank.^  &E0.  SEl 

These  lltimanaged  areas  arr  reserxeti  fiir  use  by  the  nperatinf^  system. 

Areas  of  memnry  alJoeatcd  by  ihe  Memory  Mana^icr  are  eddied  hhcks  Each  biwk 
is  identified  by  a  four-byte  address^  called  a  handk,  which  ii  returned  by  the 
fjnction  perfiirming  the  alliJt-ation.  It  is  important  to  realize,  however,  that  the 
handle  is  nut  the  address  .if  the  block  itself— instead,  it  is  the  address  of  a  20-byte 
block  record.  The  first  entr>-  in  this  rectird  is  a  pointer  to  the  block  (called  a  tmister 
pointer),  it  is  the  master  pointer  that  contains  the  address  of  the  hlcx^k-  See  figure 
4=5  for  a  pictorial  rcpresentatio!)  of  the  rHafionship  between  a  handle,  a  block 
rerard,  a  master  pointer,  and  thi^  blnxk  itself. 

The  advantage  of  using  a  handle  instead  of  a  [xiinter  to  identify-  a  block  js  that  a 
handle  to  a  hiocl;  remains  valid  even  if  the  bl(K:l<;  is  repositioned  by  the  Memory 
Manage r■-^lnly  the  address  stored  in  the  master  pointer  changes.  If  a  pointer  was 
retiLrned  in-itead.  and  the  bloL-k  wa?;  moved,  a  program  wnnld  not  be  able  to 
dett  ■rmine  the  address  to  which  the  blncik  was  moved. 

The  Memon-  Manafjev  moves  blocks  around  when  it  needs  tr>  perform  a  block- 
compaction  uperatioii.  This  occurs  in  only  two  situations:  when  you  spedfieally 
request  it  {with  CnmpactMcnij,  or  when  you  try  ti>  allocate  a  block  (with  New- 
Handle,  ReallfxIIanHle.  or  Restore  Handle)  and  fliere  is  no  free  area  large  enuujjh 
to  hold  it.  Block  compaction  gathers  together  allocated  blocks  which  may  be  scat- 
tered throughuut  memory.  This  is  done  to  eliminate  jjaps  between  blocks  and  to 
create  as  large  a  conliiuious  free  space  as  possible.  Seattcriiig  occurs  as  blocks  are 
allocated  and  deallocated  during;  program  execution. 

If  you  are  trying  to  allocate  a  block  and  there  is  no  room  for  it  even  after 
compaction,  the  Memory  Manager  automatically  frees  piirg;r-level-3  blocks  {the 
Purge  Level  attribute  is  discussed  below)  and  the  blocks  are  compacted  again.  If 
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Figure  4-5.     Block  Allnratinn  with  the  MeinoPr'  Manager 
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there  still  is  not  enough  nxim,  ptirge-level-2  blocki^  and  then  purge-leveI-1  blocks 
are  freed;  Further  mm  pactions  ottur  until  thtTi-  is  room.  An  out-of-memnr\'  error 
is  reported  if  there  is  na  ruoin  even  after  sll  thrt-f  ievt^h  of  purgeable  blocks  have 
been  purged. 

Yiiu  ciin  tdl  the  Memorv'  Manager  to  frff  (or  dispose  of)  previously  alltKJiitec] 
blocks  by  usin^  the  DisposeHandlr  functiun.  It  is  good  programmicin  praetite  to 
dtspose^  !]f  blocks  as  soon  as  they  are  no  longer  needed  so  that  as  muL-b  space  as 
possible  is  always  a\.aikble. 

Attributes 

When  you  make  a  block  allocation  retjuest  (with  NewHandle  or  ReallocHiintlltf), 
you  must  tell  thf  Memory  Maniigt-r  !he  Jttributes  ol  the  block.  Jh^se  attributes 
indicate  where  the  block  is  to  be  allocated  aiid  how  it  is  to  be  dealt  with  after 
ajlocation. 
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Figure  4-&.     The  Attribute  Wnrd  for  a  Block 
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The  attribiiles  are  passed  in  j  word;  the  hits  in  this  word  havf  the  meanings  shown 
in  figure  4-6.  Note  that  except  fur  the  LtK-kfd  and  Furjjt;  Level  attributes,  none  of 
the  attributes  cmi  be  changed  with  functitiit  calls  after  tLie  bloek  has  been  allocated. 


Locked.  A  lotked  block  is  one  th<:  Mrm^n'  Manager  is  not  permitted  to  move, 
even  ii  llie  Fixed  and  Fixed  Address  attribute  hits  arc  cff.  [n  addition,  a  locked 
block  Ci^nnot  be  purged  even  if  if s  Purge  Le^  el  is  non  /ero. 

The  Locked  sttri^nte  cisn  be  changed  afW  a  block  is  allfjcated  hy  calling  HLock 
(to  tum  it  on)  nr  HUnLtick  (to  turn  it  uflT),  Ytiu  ^liould  loek  a  block  only  when 
nccT-'isary',  such  is  when  you  need  tn  aecess  the  data  it  contains  {see  below),  and 
then  unlock  it  as  sonn  as  you  can.  Because  lotiked  blocks  cannot  be  moved,  they 
can  prevent  efficient  blnck  compaetioTi  iiijerations  and  can  lead  to  premature  out- 
of-meiTior>'  errors- 

Fixed.  Kike  a  lucked  block,  a  fixed  block  may  not  be  moved  by  the  Memory 
Manaj/er  during  a  mcinury  LtJin paction  upenltiun;  it  Slavs  put.  The  niaitl  difference 
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between  a  fixed  block  and  a  locked  block  is  that  a  fixed  block  can  be  purged  if  itst 
Purije  Level  is  nnn-^iern.  In  addition,  the?  setting  of  the  Fixed  attribute  cannot  be 
ch&ngcd  with  a  functjoji  call. 

Purge  Level.  PurpinR  a  block  means  releasing  a  block  by  setting  its  master  pointer 
lo  t)  (tile  space  fur  tke  block  record  containing  ihe  master  pointer  is  maintained  and 
can  he  reused  hy  tailing  Real loc Handle  or  Restore H an dlcK  The  purged  block  returns 
to  the  pool  of  free  memory  that  is  available  for  fiitrirc  allocation  by  the  McmoTy 
Manager,  but  the  liandle  itself  remains  alliwatcd  and  can  be  reused. 

The  Purge  Level  of  a  bluck  can  be  0,  I,  2.  nr  3.  numbers  that  reflect  the  purge 
priority:  blocks  with  higher  purge  levels  are  pi.irgcd  before  blocks  w,Tth  lower  purge 
levels.  A  Purge  Level  of  0  means  that  the  block  c;mnot  be  purged  at  all.  The  Purge 
Level  of  a  block  can  he  changed  after  allocation  with  the  SetPurf;e  function. 

Purge  \cvc]  3  is  rfscn-ed  for  use  by  the  t;s  System  Loader,  the  tool  set  riCfS]30nsible 
for  dc^,ling  wilh  FroDOS  16  load  files  (w^'hich  usually  contain  propra.nis).  Wlien  the 
System  L(>iidcr  loads  a  program,  it  fir.'jt  puis  the  previous  prugrdm  into  a  dormant 
(or  "zombie  I  state  by  assigning  a  puriJc  lc\t:l  of  3  to  the  memory  hlucks  it  uses,  It 
any  uf  these  bkjcks  are  purged,  thev  are  all  purj^ed;  if  no  purj^ing  takes  ptace  and 
eonfrttl  returns  to  the  prf>j;ram,  however,  the  System  Loader  does  not  relaad  the 
program  from  disk,  it  just  sets  the  purge  level  of  the  b[tK-k  to  zero  and  executes  the 
program. 

Vou  can  purge  purgenble.  unlocked  memory  blocks  explicitly  using  PurgeHandle, 
Fiirfiing  aLsu  uccurs  automaticdlK  if  you  call  NewHandle.  Real loc Handle,  or 
ties  lore  Handle  iUid  there  is  not  enough  space  for  the  new  block  even  after  the 
blocks  are  compacted.  In  this  situation,  purgeable  blocks  are  purged^  in  priority 
order,  until  there  is  enough  space. 

Bank-Boundary  Limited.  If  a  b3i>cli  is  Bank-Bound;iry  Limited,  it  will  he  allocated 
in  a  single  hank.  Blocks  that  contain  program  cxidc  must  have  this  attribute  set, 
because  f>,'jfjl(i  programs  cannot  cross  bank  in>undarie.'..  jVVhen  the  program  counter 
goes  from  $FFFF  to  WKHX)  at  a  bank  boundary,  the  carry  generated  is  ignored  and 
is  nut  added  to  the  program  hank  register.  That  means  execution  continues  at  the 
bottom  of  the  current  bdnk,  not  at  the  bottom  of  the  next  bank,  aS  might  be 
CNpet'ted.) 

Ordinary  data  blocks  may  span  banks,  hiiwever,  because  the  65816  indexed 
addressing  modes  let  you  index  properly  from  one  bank  to  the  next. 

Special  Memory  Sol  Usable,  If  this  attribute  is  set,  the  block  may  not  he  allocated 
in  bank  .SOO  or  SOL  or  in  any  of  the  graphics  video  buffer  areas  in  banks  SEO  or  SEl 
[$£000-S5FFF  in  itEll  ancl  $2000-S9FFF  in  bank  SEll.  You  would  set  this  attribnte 
if  you  were  resenting  memory  from  a  Ile-style  application  so  as  to  avoid  allocating 
areas  in  the  128K  program  space- 
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Page-Ahgncd.  If  the-  liloclc  is  PaRe-Aljgnt'd.  it  be^^ins  at  an  address  uf  the  form 
$l)b.KK[H).  that  is.  at  the  beginning  of  a  mL'mnry  pagt--  memory  page  is  the  256 
bytes  extending  from  address  SbbxxOO  to  SiilmxFF  )  You  shimid  set  ibis  iittiibutc 
when  allocating  space  tn  lie  used  as  a.  65816  direct  page  so  '^s  to  niuxhni/e  the  speed 
of  direct  page  operations.  A  direct  page  npfratiuii  still  works  if  the  page  is  not 
aligned,  but  it  lakes  one  cycle  longer  lu  ex^-cutc  than  ii'it  is  aJigned. 


Filed  Addresif.  Set  this  attribute  if  you  want  a  block  to  be  allocated  at  a  speeific 
lnjcatian  in  m^i'nion..  \ou  might  want  to  do  Lhis.  for  iiistaiiee,  to  align  a  bloL-k  with 
one  ol  the  graphics  screen  video  buffers.  The  us  operating  system  uses  this  attrilmtp 
when  it  reserves  specific:  memory  areas  at  start-up  time, 


Fixed  Bank.  If  the  Fixed  Banlt  attribute  is  on.  the  Memorj^  Manager  will  al- 
locate a  block  in  the  bank  spedfied  when  you  eaJl  NewHaiidle,  ReallocHandle,  or 
Resforellandle.  You  must  set  thi.'i  uttributp  wlien  allocating  direct  page  and  stack 
space,  becauie  the  65816's  direct  page  and  stack  must  be  in  bank  $00. 


Aeces^sing  a  Blofk 

To  read  data  from  or  write  data  to  y  block,  yoll  need  to  know  the  address  of  the 
block.  Tq  get  it,  you  must  first  dereference  the  liundlc  to  the  bluck  to  dptermine 
what  the  master  pointer  is.  Then,  you  can  address  tlie  block  by  storiiii^  the  master 
pointer  m  direct  paj^e  and  ijsiiig  the  [dp],Y  indirect  addressing  mode,  (Reca!l  from 
chapter  2  that  tlie  brackets  iJlditate  that  this  is  a  loiiK  addressing  mode,  not  a  short 
addressing  mode;  the  pointer  to  the  ?ilart  of  the  blixk  is  stored  at  dp,  dp+1,  and 
dp+2,  where  dp  is  a  direct  page  address.  J 

In  the  example  to  foUuw,  a  256-l>yte  block,  whose  handle  is  ^itored  at  MyHaiidlc, 
is  filled  with  ztroes.  The  first  part  of  the  subrontiiie  dereferences  the  handle 
(DPScratch  and  ToBlock  are  the  direct  pa^e  addresses  of  two  faur-byte  area^.): 


1 6-bi I  A  reg  J  s  ter 

LDA  rij^Handte 
ETA  DPScratch 
LDA     MyHaTidle  +  2 
STfl     DP5ci-fltch  +  2 


;Put  handle  in  direct  page 
;    sa   that    the  master  pointer 
;   can  be  accessed  with  an 
;    indirect   Icng  addr  made. 


LDfl  [DPScratch] 

STfl  TflSloct 

LDV  #2 

LDA  IDPScratch] ,Y 

STfl  ToBlocfc+2 


;Get  ma^tier  pointer  (low) 


;C«t  maater  painter  (high) 


LDV  #0 
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ClesrBlk      STfi      lToBl-ock],V  iBtore  a  zero 

INV 
INV 

BME     ClearBlk  ;Branch  uritil  V=£5S 

RTS 

An  importanb  caveat;  You  cannot  use  a  derfferenced  handle  to  aecess  a  black  if  the 
block  may  havK  been  moved  (bccaust;  ot  coinpaclion)  or  purged  by  the  Memory 
Manager  sincti  the  time  yoii  did  the  dereferencing — it  may  not  point  to  the  block 
anymore.  Com  pat-lion  and  purging  can  ot-eur  if  yon  call  the  Memory  Manager 
directly,  if  you  call  a  tool  set  ftmctjun  that  ealls  the  Mcmiin,'  Manager,  or  even  if  an 
interrupt  oceurs  (the  interrupt  h^indler  eoukl  cjII  the  Mt^innry  Manager). 

To  prevent  the  movement  or  i>urf;inK  of"  a  block — and  to  uiaiutain  the  validity  of 
a  dereferenced  handle — lock  the  block  iti  place  with  the  HLjxk  function  just  before 
you  dereference.  If  you  do  this,  be  sure  to  unlock  the  block  (with  HUnLnckl  when 
you  are  through  using  the  dereferenced  handle.  The  alternative  is  to  avoid  calUng 
tool  set  functions  which  may  use  the  Memory  Manager  and  to  disable  interrupts, 
rcstrictiiins  which  are  usually  impraetical. 

If  you  choo.se  not  tn  lock  the  block,  you  should  dereference  the  handle  to  the 
block  every  time  you  want  to  access  the  block's  data,  but  even  this  may  not  work  if 
interrupts  are  occurring. 

Of  course,  you  do  not  have  to  woirry  abrnit  locking  a  block  (or  unlocking  it)  if  you 
set  the  Fixed  or  Fixed  Address  attribute  when  the  block  was  first  alliK-ated  (and  the 
block  is  not  purgeable)  or  if  you  set  the  Locked  attribute. 

MEMORY  MANAGER  FUNCTIONS 

There  are  many  memory  manai^er  functions  at  your  disposal,  but  most  applications 
will  use  only  a  core  group  of  si.\  major  functions.  This  chapter  looks  at  this  core 
group  and  then  reviews  most  of  the  minor  functinns.  (See  table  R4-J  at  the  end  of 
this  chapter  for  a  siiminaiy  of  the  major  memory  manager  functions.) 

The  Major  Functions 

Start-up  and  Shut-Dotvn,  Like  all  tool  sets,  the  Memory  Manager  has  a  start-up 
runction.  MMSlartup,  that  your  application  must  call  before  it  can  use  the  Memory 
Manager-  BfcaiiAc  almost  every  other  tool  w;t  unplicitly  u^es  the  Mcrnor>'  Manager, 
you  must  call  MM  Startup  before  calling  the  .startup  function  of  any  other  tool  set 
except  the  TiKil  Lijcalur  and  the  Mi-sccllaneous  Tool  Set. 

MMStartup  takes  no  input  parameters,  but  it  does  return  a  result — an  Owner 
ID  [a^.  The  ID  tag  is  an  identificalian  code  assigned  to  the  program  when  the 
System  Loader  loads  it  Into  menmry  prior  to  execution.  It  is  to  be  used  to  mark  all 
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blocks  pllwated  hy  the  applk-ation-  It  also  identifies  the  blocks  to  be  included  in 
t'ertain  group  operiitioos  the  Memory  Manager  L-an  perform, 
Here  is  how  tn  imW  MMStartup: 


PHA  ^Spac  e  for   result  (word) 

_nin5  lart  up 

PLA 

STA  MylD  ;Save    ID  cade 

MylD  is  a  two-byte  data  area  that  can  be  allocated  witli  a  data  allocation  directive 
of  the  form: 

MylD  DS      2  iflllocBte  byteg 

You  should  save  MylD,  htL-auie  you  will  need  it  to  start  up  other  tool  sets. 

MMShutDown  is  the  shut-down  fimction  for  the  Memory  Manager.  Call  it  jusl 
before  the  iipplication  ends,  after  shutting  down  all  other  toul  sets  (escepi  the  Tool 
Locator  and  the  Miscellaneous  Tool  Set).  MMShutDciwn  has  one  input  parameter 
(*he  ID  tag  returned  by  MMStartup)  and  retunis  nw  results: 

PushWord  MylD 
PinShutDown 


Note  that  MMShutDnwn  dutfS  not  free  up  all  memory'  blocks  associated  with  MylD. 
This  is  done  by  FrnDOS  16  when  it  regains  control  after  a  ProDOS  16  QUIT 
command.  You  can  exphcitly  free  up  memory'  blocks  with  the  DisposeHandle  bine- 
tion  (see  below), 


Block  AUocation,     NewHaiidle  is  the  primary'  block  allncatian  function.  With  it 
you  can  create  blocks  of  any  size,  with  any  attributes,  and  you  can  associate  them 
with  any  ID  tap.  NfwHandlc  returns  a  handle  to  the  alliicated  block. 
The  general  calling  sequcnLt'  UnAn  like  this; 


PHfl 
PHfl 

PiishLatig  BiockSize 
PuahWord  OwneriP 
PushWor  d  fltlrihLites 
PusfiLong  Locaticn 
_Ne-wHand  le 
PopLorg  MyHandlp 


^SpacE  for   result  (longji 

;Siie  of  bir>el( 
iOwh^r    ID  lag 
;  At  tr  ibu  te5  of  hloc  I: 
;Addre55    of  block 

jPop  handle   to  blacl 


(Recall  from  chapters  2  and  3  that  PwshWnrd.  PusliLong,  and  PopLong  are  macros, 
not  (i^filG  injitructionS.) 

BlockSize  is  the  size  of  the  block  to  he  created,  in  byte.s,  OwncrlD  i-s  the  ID 
code  to  he  assigned  to  ttie  block  and  is  normally  the  same  a.s  the  ID  e<ide  relumed 
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by  MM  Startup,  Attributes  is  the  attribute  wurtl  for  the  blot-k.  Laciation  is  the  starting 
address  of  the  block  and  is  mtfiniiiRfu!  cinly  if  the  Fixied  Address  nr  Fixed  Bank 
attribute  is  set- 

NewHandle  does  all  it  can  tu  reserve  the  requested  space,  including  bU)ek 
compaction  and  purfjiTig,  if  necessary,  The  handle  that  is  retiin\ed  pnints  In  a  bJock 
record  made  up  of  the  followinij;  elements: 


•  Address  of  bluck  (4  bytes) 

•  Block  attributes  (2  bytes) 

•  Owner  ID  ta|(  (2  bytes) 

•  Size  uf  bJock  [4  bytes) 

•  Address  of  previous  block  recnrd  (4  bytes) 

•  Address  of  next  block  reciord  (4  bytes) 


If  the  record  is  the  first  or  last  one  in  the  list  niiiintained  by  (be  Memory  Manager, 
the  pointer  to  the  previous  block  record  or  to  the  next  block  record  is  zero. 

Notice  that  in  the  previous  esamplf.  BUwrkSize,  Attributes,  and  Location  are 
passed  variables  (nunibers  stored  in  mcmor\-  locations),  even  tbuu^  you  are 
probably  more  likely  to  pass  them  as  constants  (immediate  values).  To  pass  constants, 
precede  the  constant  with  "#"  to  inform  the  PushLonji  or  PusliWord  macro  that  it 
is  a  constant.  For  instantf.  to  allocate  five  pa^e:^  of  memory  in  l>ahk  $tX)  for  passible 
use  as  direct  pages  by  other  tools,  call  NewHanille  like  thisr 


PHA 
PHA 

PuatiLong  #1500 
PuatilJord  MylD 
Pu5hNord  #SCCOS 
PuahLong  #0 
_He"'Ha  nd  1  p 
PopLcng  PlyHardle 


;5pace  for  result  (long) 

\Five  pages    (1500  byte*) 
; ID  returned  by  MMStartup 
^Locted,   Fixed,    Fixed  Ban* 
; Address  :    ban  k  SOO 

;Pop  handle   to  bLoct 


Pi  I  i  gned 


Nutice  the  attribute  word  for  this  block:  $Ctl05.  Because  a  direct  page  must  be  m 
bank  SOO.  the  Fixed  Bank  attribtlte  (bit  0)  is  set.  Because  fj5816  direcl  pa^e  instruc- 
tions work  more  quickly  when  direct  page  begins  un  a  psRe  boundar>',  the  Page 
AiiRiied  iillribiite  (bit  2)  is  also  ,»;et.  The  I^K-kcd  attribute  [bit  151)  is  set  so  that  the 
bliK-k  will  not  move  annind — this  means  that  you  will  have  to  dereference  its  handle 
only  once  to  access  it.  Finally,  the  Fixed  attribute  [bit  14)  is  set  so  that  the  block 
will  not  move  even  if  it  is  accidentally  unlocked. 
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Bhjik  Deailofution.  As  xiion  as  you  an^  finishciJ  with  a  previously  allocated  bloclt 
(»!' meiiiiin,  ^Dii  should  Irt-t-  11  up  .inain  hi  cliiiiin^te-  the  possiliility  of  an  early  oiit- 
uf-nit'imirv'  frrt>r,  Tu  dti  thb  ymi  (mii  usf  t!ic  13is]icisL  [[autllf  lunoiioil: 

PuahLoTig    MyHandle  jHandle    to  block 

_Di sposeHandie 

Dispose  Handle  also  rcmnvcs  thi-  t'lilry  for  Ilit  iiiasler  pointer  in  the  Memc>r\- 
MaiiiiEtr's  list  i»J"inii,*^tcr  piiiiitfis.  Tliis  means  that  you  cannot  reuse  the  handle  with 
Ht'itllofHuudk-  ur  Ri-slnn-HandlL'. 

DispiiSfHiiiicIlL'  doc^;  its  diitit-K  even  if  the  hlot-k  is  locked  or  not  purgcable, 

Locking  and  Uniocking,  Blocks.  As  miciitiuned  earlier,  it  is  itlll>orfiint  tn  liotk  a 
ino^f'^iibU"  []r  purKcahk-  IJuL'k  to  L-nsure  its.  lie  re  fere  need  haiulk'  remains  valid  I'or 
data  accesses.  The  functinn  for  duing  this  is  IILock^ 

PuahLong  MyHandle  jHandle   to  black 

_HLdc  k 

The  runcliuii  (or  unlocking  a  hlix-k  is  .HUnLock.  It  also  takes  a  handle  to  the  block 
as  its  only  parameter. 

The  Minor  Fun-L'tiun^ 

Most  applications  will  nciit  need  to  use  the  reinsining  Metnor>  Manajijer  functions 
vrr>'  often — they  ar^'  used  priinariK'  \i\  the  operating  system.  Xc'VLTthck-ss,  it  is 
iiniMjrtant  tu  betonif  tauiilisir  with  them  so  that  you  will  rcuv^nize  h«jw  to  handle 
those  ^ituatiiins  L'alling  lur  their  use, 

Reailocation  of  Purged  Elockn.  if  a  blcK:k  has  heeri  purged,  its  master  ptjinttr  is 
set  to  0,  but  the  space  occupied  by  the  master  poitkter  is  not  freed.  To  reuse  the 
ma.'^ter  ijointer  nfa  purged  block,  call  Reallucllaiidle.  It  hfhavps  just  a.s  NrwHandle 
does  except  that  it  ri-c)Liircs  iiiie  additional  parailleler.  the  hiUldle  Ko  the  purged 
block-  Thii*  is  tbr-  last  parameter  pa&sed;  tile  ttther  parameters  arc  pushed  first  in 
the  same  order  '^s  fur  NcwHaiidle.  You  tiuiv  find  it  simpler  to  use  ReslureHandle. 
It  nef'ds  (inly  tbe  handle;  tlie  Kle  attributes,  owner,  ami  size  previously  used  are 
retained. 

When  allocating  space  for  a  purfjed  block,  you  should  resist  the  temptatidn  to 
use  NcwHantllc.  II  you  do  Iu^t  reuse  purged  handles,  you  will  wa^te  memory  (20 
bytes  ]]c]  handle,  tlic  size  of  the  block  record)  and  Memory  Manager  operations 
will  bf  ii  bit  sitJwtT. 

Disposing  and  Purging  Bl/Kks.  We  saw  earlier  tliat  Dispose  Handle  frees  only  the 
block  assuciated  with  a  particukr  handle.  With  DisposeAll.  you  can  free  up  a  group 
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of  bluL'kii  at  once,  each  asiuici^ited  with  the  same  ID  tag.  To  use  DisposeAll,  pass 
the  ID  tag  as  a  paramfter: 

PushUord   Own^rlD  I  D  tag 

_Dl spoiF A  1 1 

This  example  deposes  uf  all  blocks  a&!^aciated  with  OwnerlD,  Do  not  tr>'  to  dispose 
of  all  blocks  marked  with  [he  ID  of  the  program  itsplf,  because  the  memory  the 
program  occupies  could  he  ove^Titten  before  the  program  ends. 

Another  way  to  free  up  space  is  to  purge  a  block  or  group  of  blocks  with 
PurgeHaodle  or  Pur^eAll.  Both  functions  will  purge  any  unlocked  hlotk.  e\en  if 
the  block's  pur(;e  level  is  0.  The  input  parameter  for  Pur:H;eHandlc  is  a  handle  to 
the  block  to  be  purf^ed.  The  parameter  foi  PurgeAll  is  an  ID  tag — all  blocks,  with 
the  specified  ID  are  purged. 

Setting  Attributes.  Only  the  Locked  and  Fur^e  Level  attributes  of  a  block  can  be 
modified  after  thp  block  has  been  alltujatcd.  HLi.ji.'k  and  HUnLock.  which  lock  and 
unlock  individual  bltK'ks,  have  iilready  been  discus::ed.  Two  other  functions, 
HLockAll  snd  HUnLockAU,  lock  and  unlock  ii  f^roup  of  blocks  with  the  same  ID 
tag.  Pass  the  ID  tag  tin  the  stack  before  caUin^  either  of  these  functions, 

To  set  the  purye  level  uf  a  blocks  use  SetPurge.  It  takes  two  parameters:  the  new 
purge  level  (a  word  from  0  to  3)  and  a  handle  to  the  block: 

PuahUgrd  #1  ;PurgeLeuel=l 
PushLong  MyHandle  iHaodle  to  bicck 

_Sb  t  Purge 

SetPurgcAll  sfjts  the  purfje  level  of  even-  block  with  a  given  ID  tag.  The  two 
parametej^  it  requires  are  the  new  purge  level  and  the  ID  tag. 

Biack  Information  Functions.  KindHandle  takes  a  memory  location  as  an  input 
parameter  and  returns  a  handle  to  the  block  in  which  it  is  located-  For  instanpe,  a 
prngram  can  deduce  the  handle  to  the  block  id  which  it  is  currently  running  by 
executing  the  foFlowiag  segment  of  code; 

PHfl  ;Spflce  for  reiult  (handle) 

PHfl 

PuatiPtr      MyLabel  jPusli    long  address 
MyLebel  _FiridHandlc 

PopLofig  Cofl*Hndl  I  Pop  ttie  result  (tiandle) 

GetHandleSize  takes  a  handle  as  an  input  parameter  and  returns  the  size  oi  the 
hloiik  to  which  it  refers.  To  get  the  size  of  the  code  segment  in  the  above  examplie, 
use  the  following  code: 
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PHA  ;Spacc   ^or    reault  (long) 

PHfl 

PushLong  CodeHndl  (Handle   to  code  block 

_GetHandlcSiiE 

PopLpng  Size  ;Pop   the  result  (InTig) 

Use  Set  Handle  Size  to  expand  or  contract  the  size  of  an  existing  block.  The  input 
parameters  are  a  handle  tg  the  block  and  the  new  size  of  the  block  (a  long  word). 
Fur  example,  suppose  your  code  block  has  an  initializatiou  sequence  743  bytes  long 
which  is  located  at  the  ver>'  end  of  the  block.  If  you  expect  to  be  tight  on  memory 
spiLi?,  you  inay  want  to  dispose  of  it  after  you  arc  through  with  it.  Here  is  how  you 
can  do  t]iat: 


PughLong  CodeHndl  ;Pu9h  handle  ia  code  block 
SEC 

LDi^  Siie  ;  Ntw  ali«  -  old  size 

SBC  #743  1  minua  7^5. 

LDA  Siie+2 
SBC  #0 
PHfl 

SclHandle5i2e 


Data  Movejnent.  Tlie  MRmory  Manager  has  four  functions  tliat  permit  you  to 
move  a  block  of  data  from  ani-where  in  memory  to  an>Tvhere  else  in  iiienior>'.  All 
yuu  need  is  a  pointer  nr  handle  to  tlie  start  of  the  source  block  and  to  the  destination 
block.  If  you  use  a  handle,  the  xVlemory  Manager  function  takes  carenf  dereferencing 
it. 

Here  is  a  summary'  of  how  each  of  the  four  data  moveinent  ftinctions  work; 

PtrtoHand         Move  a  block  referenced  by  a  pointer  to  a  block  referenced  by 
a  handle 

HandtoPtr         Move  a  block  referenced  by  a  handle  to  a  block  referenced  by 
a  pointer 

HandtoHand       Move  a  block  referenced  by  a  handle  tn  a  block  referenced  by 
a  handle 

Bl  DC  kMove         Move  a  block  referenced  by  a  pointer  to  a  block  referenced  by 
a  pointer 

Each  function  requires  three  long-word  parameters  on  the  stack--  a  pointer  or  handle 
to  the  source  block,  a  pointer  or  handle  to  the  destination  block,  and  a  count  of  the 
number  of  hytcK  tn  move. 
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Be  very  careful  when  using  the  data  movement  functions.  They  do  not  verify  the 
vaJidity  uf  hdndles  and  pointers,  and  they  do  not  check  to  see  if  the  destination 
blocle  is  luj^e  fi^nuugh  to  accommodate  the  transfer. 


Free  Space  Functions.  Three  Memory  Manager  Junctions  relam  numbers  reflect- 
ing the  sizes  of  various  spaces  in  the  system: 

FreeMem  returns  the  numher  of  free  bytes  in  memory.  The  number  does  not 
include  the  space  occupied  by  purgeahle  bloeks.  FieeMem  does  not  compact 
memory. 

MaxBIcx:k  retumi  the  size  ol  the  largest  free  block  in  memory,  MasBlock  does 
not  compact  memory  and  it  does  not  purge  purgeable  blocks.  The  number 
returned  by  MaxBlock  cannot  exceed  the  one  returned  by  FreeMem  because 
of  block  fragmentation. 

TotalMem  returns  the  size  of  the  RAM  space  in  the  sysiem. 

None  of  these  functions  t^es  input  parameters,  and  all  three  functions  return  a 
long  word  {the  size  in  bytes). 
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Table  B4-1:     The  Major  Functions  in  the  Memory  Manager  Tool  Set  ($02)  


Funciion  Name 

Function 
NuTitber 

Stack 

Description  of 
Parameter 

BlotkMove 

$2B 

Source  Ptr  (L) 

Pointer  to  source  block 

DestPtr  (L) 

Pointer  to  destination  block 

Count  (L) 

Numher  of  bytes  to  copy 

CheckHandle 

$1E 

TheRandle  (L) 

Handle  to  be  validated  (*) 

Compact  Mem 

$IF 

[no  parameters] 

Dispose  All 

$11 

UserlD  (W) 

ID  tag  for  blocks  to  dispose 

DisposeHandle 

$10 

TlieHandle  (L) 

Handle  to  block  to  dispose 

FindHsndle 

$1A 

result  {L] 

Handle  for  block 

MemLocation  (L) 

Location  to  test 

FreeMem 

S]B 

result  (L) 

Amount  of  free  memory 
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Function  Name 

F  unction 
Numtter 

Siack 

Parameters 

G<'tHaridle.Si?e 

SIS 

rf<:iilh  If  \ 

HandtoHand 

S2A 

l-ZtrMriLlUl  \l-r/ 

Cnunt  (I  1 

HandtoPtr 

$29 

S  ni  1  vr*^  H  TB  ri  r  f1  ^ 

DestPtr  (L) 

Cuunt  (L) 

11  Lock 

HLock,4il 

IherlD  (W) 

HUnLnck 

TheHandle  [U 

HUiiLockAll 

$23 

UserlD  (W) 

MaxBlotk 

nc 

result  (L) 

MM  Shu  I  Down 

S03 

U^crlD  (W) 

MMSlarlup 

$02 

result  (W) 

NewHandle 

$09 

result  iU 

UL\iicriptioti  of 
Parameter 


PtrtoHand 


BloukSize  (L) 
UserlD  (W) 
McmAttrib  (W] 
Mem Lueation  [L) 
SourctrPtr  [Lf 
DestHiidl  (L) 
Count  (L) 


Size  of  block  in  bylcs 

Handle  to  block 

Handle  to  source  bltitk 

HandJc  to  destinatinn  blotk 

Number  iif  bytes  Lo  copy 

Hiindli?'  to  souTLf  block 

Pointer  lo  destination  lilotk 

Number  of  bytes  tw  copy 

Handle  to  block  to  luck 

ID  tag  of  blocks  ttj  lock 

Handle  lo  block  to  unlock 

ID  tag  for  blotks  to  unlock 

Size  of  largest  free  block 

ID  tag  returned  by 
MMStarlup 

ID  t;lJ^  for  metnor^' 
allocation 

Handle  to  new  iiieinory 
block 

Size  of  memory  block 
ID  lag  for  memory  block 
Attributes  uf  memory  block 
Allocation  address 
Pointer  tn  source  bli>ck 
Handle  hi  destination  block 
Number  of  bytes  to  copy 
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Function  A'arne 

Functitm 
Numhtt 

Stack 

Oescriptiim  of 
Parajneter 

ParRcAII 

ATS 

$13 

UseriU  (WJ 

ID  ta^  ffir  bluL'ks  to  purgff 

r  urge  Handle 

1?  1  n 

Hiuidle  to  purfic 

Healloc  Handle 

Dlofkaize  (LiJ 

ni  jncnKiry  l>ivx.k 

User  ID  (W) 

ID  tag  for  memory'  block 

MemAttrib  (W) 

Attributes  of  memnry  block 

MeiiiLoc?ation  {L} 

Allocatknn  address 

Thellatidle  (L) 

Hiindle  to  re-use 

Restore  Handle 

SOB 

TlicHandle  (L) 

Handle  lo  be  restored 

Set  Han  tile  Size 

$19 

NewSize  (L) 

New  sviie  of  block 

TheMaiidle  (L) 

Hundle  to  block  tii  he 

resized 

SetPuTRS 

S24 

PurgeLevc]  (W) 

New  purge  level 

TheHandle  (L) 

Handle  to  memory  block 

SetPurgeAll 

$25 

Ptir>;eLevel  (W) 

\ew  purge  level  for  blix-ks 

LTyerlU  (WJ 

ID  lag  for  blotkh  involved 

TotaJMem 

$1D 

result  [L) 

System  memory  size 

•  For  ChBtk^Unilk-,  ail  error  code  of  SU206  is  relurned  if  ibe  tiundile  is  not  valid 


Table  K4-2j     Memory'  Manager  Eritir  Ccxle*  

Error  Code   Description  of  Error  Condition  

$0201  Out  nf  meinory  :  the  block  was  not  ailocated. 

$0202  Tbe  operation  failed  because  tbe  block  has  been  purged. 

Reference  Section  1^3 


Error  Code  Deicription  of  Error  Condition  

f0203  An  attempt  was  made  to  reallocate  (with  Realloc Handle}  a  handle  of 
a  block  that  has  nut  been  purged  yet. 

$02U4  The  operation  failed  because  the  block  is  Locked  or  immovable. 

$0205  An  attempt  was  made  to  purge  an  unpurgeabb  block. 

$0206  The  handle  does  not  exist. 

$0207  The  [D  (ag  does  not  exist. 

S0208  Illegal  operation  oa  a,  block  with  the  specified  attributes. 
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CHAPTER  5 


Event 

Management 


All  important  part  of  any-  application  program  is  the  todc  that  cheiks  for  user  input 
and  responds  tn  it  in  an  appropriate  way.  The  two  main  sources  of  user  input  on 
the  cs  are  thr  kt-yboard  and  thi?  mouse,  hut  int-CDming  data  can  also  fome  from  aiiy 
other  device  on  the  Apple  DcskTwp  Bus  or  froo\  a  dcvia-  tonnetted  to  a  port  or 
slot.  The  occurrence  of  a  discrpte  clement  of  input  activity  is  called  an  event  and 
the  tool  s;et  an  application  ii'^cs  to  monitor  events  i%  called  the  Evt-nl  Manager. 

The^  Event  Manager  actually  handlsfs  more  than  just  traditional  mouse  and  key- 
board events.  It  also  manages  two  window-relsted  operations  that  take  place  when 
the  appearance  of  a  window  on  the  graphics  screen  is  to  be  changfd — namely, 
activate/deactivate  events  and  update  events.  (Windows  will  be  discussed  in  detail 
in  the  next  chapter,)  The  as  tiperaliog  system  treats  activate/deactivate  and  update 
activities  as  events  to  mabie  it  easier  to  develop  softw^'are  working  in  a  multiwindow 
enviroim^ent. 

THE  EVENT  LOOP 

Any  cs  application  that  uses  the  desktop  environment  should  he  event-driven.  That 
is,  the  applicatifm  sliould  be  ready,  at  aJl  times,  to  react  to  any  event  which  might 
occur-  It  should  avoiil  ptiltinp;  the  user  in  a  mode  that  restricts  the  group  nf  aictions 
the  user-  niav  pcrtumi,  liccausc  this  only  series  to  frustrate  the  user.  Of  course, 
there  arc  times  when  restrictive  modes  are  desirable,  such  as  when  the  application 
wants  t(j  force  the  user  to  respond  to  an  important  question  before  pnx.'eedins 
fijrthcr,  hut  such  niotles  are  not  needed  often. 

An  cvcnt-diiven  apphcation  spends  most  oi'  its  time  io  an  event  loop,  in  which 
it  repeatedly  cbeek.s  for  the  occurrence  of  an  event.  When  an  event:  ocjcurs,  the 
application  responds  to  it  and  then  returns  to  the  Innp  and  waits  for  the  next  event. 
Here  is  tlie  simplified  flowchart  of  an  event-driven  applitc".itioti: 
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As  you  can  see,  the  maiit  task  of  an  event  loop  i^i  lo  chwlc  whether  nii  event  has 
nc-furrt-d.  This  is  n  very  simple  lask  iri\n|viiiE  the  use  of  the  Event  Managtrs 
GetXextEvc-iit  function.  Tfii-  :itHiiiI  liandliiig  of  t-verit  is  more  complicated  but 
still  quite  .straishtft]rward.  Tht-  most  difficult  part  of  any  iippHcatitni.  uf  wiurse,  is 
the  part  dcluaKy  perfnnninn  thf  tasks  stlceted  by  the  user. 


Initializing  the  Event  Manager 

Chapter  3  explained  diat  hofore  you  can  nse  any  tool  set  ynu  must  initialize  it  hy 
tallins  its  start-up  fiinctiun,  The  namt-  nf  thi'  start-up  ruuctinn  for  the  Event  Manaj^-cr 
is  EMStartijp.  Call  ii  rifilit  after  starting  up  l!ie  Tool  Lcitator  and  Ihf  Memory 
Manaj;i-r  wilh  calls  to  TLStarUjp  and  MMStartup. 
J'he  eallinR  Kectuente  fur  EMStartup  luoki  like  this: 


PuatiWord  DPflddr 

PushWord  #!iJ«1inCiamp 
PushWord  ffSMaMClamp 


;Dnf'  p^qs    in  bank  SQD 
;Si.ze  of  event  queue 
;Mfi4j5e  miFiimum  (honz; 
;riaii5e  maximum  fhoriz' 
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PashUord  #yMir.Clamp  iMouse  irinimum  (verl) 
Pa5hWard   #YMairCllanp  maximum  {uerlj 

PiishWord  UserlD  ;!D  returned  by  MMSlartLip 
_EnStar  t  up 


EMStartiip  does  not  return  a  result. 

DPAddr  is  the  slartin;;  address  oF  a  256-byle  area,  in  h.mk  $00  that  (he  Fvtnt 
Manager  uses  as  a  dircL-t  pa^t.  EMStartup  puts  this  address  in  tht-  Work  Area 
Pointer  table  using  the  Tfxjl  Locator's  SelWAP  function.  Use  the  Memory  Manager's 
NewHandle  tall  to  allocatt:  the  bank  $00  space: 


PHA 

PustiLang;  j(!25G  ;Hced  one  page   <25e  byte*li 

PushWord  UserlO  J  ID  relLrnad  by  PinStartup 

PuahWord  #tCOOB  ;Lacked,    Static,    Fixed  Bank,  ftlagned 

PushLong  #tDaQ'000  ;AddrB55:   bank  tOO 

_NewHaridle 

PopLong  HyHgndle  jPop  tiardie  to  bloct 


To  determinf!  the  aLtiial  direct  page  addres^^  ta  he  ii.^ed  ai  UPAddr,  yuu  must  first 
dereference  the  iiaiidlr  usinj;  the  techniques  described  in  the  kst  chapter.  The 
address  is  the  low-order  wt>rd  of  the  dereferenced  handle. 

QiieucSize  is  the  iiumber  t}f  eveuts  the  Lveiit  Manager  tan  keep  track  of  at  one 
time-  The  events  ^rt>  posted  in  ii  giieiie  tliey  are  detected  and  are  removed  one 
at  a  tim*-  as  the  appUcJtion  eiJIs  CctNextEvent.  !f  the  applicatKin  does  not  retrieve 
events  from  the  queue  often  enough,  the  qucne  rcmld  fill  up,  taubing  older  events 
tfi  be  lost  as  they  arc  replaced  by  more  recent  events.  QueueSi^e  must  be  an  integer 
between  0  ajid  36.39  If  a  value  of  0  is  specified,  a  deliiult  size  of  2«  U  used;  tliis  is 
a  suitable  size  for  mnst  application-s. 

The  four  damp  piir^nieters  deserilie  the  coordinates  of  the  rectangle  in  uhlch 
the  mouse  pointer  will  he  confined  tin  the  screen,  XM inClamp  and  XMaxClamp 
refer  in  the  left  and  risht  sides  of  the  rectangle,  and  YMiiiClamp  and  YMaxClainp 
refer  to  the  top  and  bottom  sides.  The  clamp  parameters  are  usually  set  to  the 
coordinates  of  the  full  ^raphif:  wreen  so  that  the  user  can  point  (o  any  object  on 
the  sereeji.  This  means  that  XS[in<:]auip  and  VMinClamp  u-ill  be  0.  and  YMaxClainp 
will  be  200,  The  value  of  XMa-xtdamp  depends  iin  Uie  graphics  mode  in  use;  it  will 
be  3aO  far  320-by-200  mude.  or  640  for  640  hy-200  modr.  To  ensure  that  you  can 
always  see  the  inciuse's  arrow  cursor,  however,  you  may  want  to  set  XMaxClamp 
and  YMaxClamp  to  values  that  are  two  or  three  pixels  smaller  tha»  the  full  screen 
dimensions, 

UserlD  is  the  ID  todf  returned  by  MMStarlup.  It  is  used  when  the  Event 
Manager  calls  the  Memory  Manager  to  allocate  any  blocks  it  needs  to  operate- 
To  shut  down  the  Event  Mana^?er,  call  EMShuldow.ii.  It  requires  n«  parameters. 
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Tabic  5-1;     Evt-nts  llriiiJIi'd  In  the  Invent  Manri^er 


Mouse  Events 

M  t>iisf-d(m  n 
Moust:-u[j 


Keyhoiirtl  Events 
Ktn'-tlmvn 


Windotf  Ei  i'iits  Sfjeciiil  Events 


Update  Desk  accessory 

ActivatL'  Switch 

Dt'vit  r  driver 
Applicatinti -dp fined  (4) 


EVEXT  TYPES 

The  Event  Maunder  supports  16  typen  iif  L'Vt-nts.  Tl:  s  includes  a  null  event  that  is 
Tt'ijorted  when  no  olher  type  of  event  has  lahen  pktt  '  efbre  a  request  for  an  event 
is  niadu'  with  CetNexlEvenl,  Tw'O  tii  the  Ifj  event  ly  .-a  are  nitt  cuirenth'  in  use,  so 
there  art'  really  only  14  evt-nt  types  tliat  niiiy  he  rL-[)urted 

The  different  events  liandlfd  by  tlie  Event  Manager  ean  be  broken  into  Four 
groups:  niiin>ic  fvciits,  kiivbtiard  events,  window  events,  and  s^pecial  events.  See 
the  hre^ikdown  in  table  S-L 

Mouse  Events 

ThtTf  ar['  twn  mouse  events,  nioiise-down  and  muuse-up,  A  mouse-down  event 
Oeeuri  when  a  rt'lcasrd  mouse  hnltnn  is  pressed.  A  inuuse-up  event  ueturs  when  a 
pressed  mijit^ie  button  is  relcasrd- 

The  Evt-nt  Man;ii;er  actually  wnrk^  with  a  two-buttoti  jnouse  (or  ail  alternative 
pciintiny  devicf  with  two  buttons),  hut  the  same  event  tcides  for  mouse-up  and 
luouse-do^Ti  arc  reported  for  cithrr  buUon,  You  can  deferniiue  which  button  was 
actually  inv  nlvpci  in  the  event  by  e\aniiniiig  the  Mudifier,s  field  of  the  event  record 
returned  by  Cct\e\lEvent,  a&  you  will  sec  latf  r  in  this  chapter. 

You  can  determine  the  state  of  the  mouse  button  directly  with  the  Button 
function; 


PHfl  ;apace  for  result 

PiishWDrd  )C0  ;tiuttoin   number    {0  or  1) 

.Button 

PLfl  jTrue   =  button   la  down 

For  the  standard  CS  inouie,  the  buttim  number  must  always  br  zero.  The  Boolean 
result  is  true  (non-zero)  if  the  buttim  is  down  or  false  (zero)  if  it  is  not. 
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Keybuard  Events 

The  two  Iceyboaid  events  are  key-down  and  auto-key.  A  key-dovm  event  occurs 
when  a  released  character  key  is  pressied,  A  character  key  U  <»ne  which  generates 
an  ASCII  character  code  when  pressed  by  itself  Evcr\-  key  (in  the  keyboard  is  a 
character  key  except  the  Shift,  Caps  Lock,  Open-Apple  fCnmmajid],  Control,  and 
Option  (Solid-Apple)  keys.  These  keys  are  called  iiuidijiur  kei^s  because  they  are 
usually  pressed  at  the  same  time  iis  a  character  key  to  change,  ur  modily,  the  ASCII 
code  it  would  otherwistf  generate. 

If  you  hold  down  a,  character  key  long  enough  it  will  besin  lo  repeat  itself  The 
act  of  repelitkiii  is  called  an  auto-key  event-  The  repeat  rate  t^an  be  set  with  the 
Control  Panel  desk  acccssury;  you  can  even  turn  off  the  auto-repeat  feature  if  you 
wish, 

Window  Events 

The  (wo  window- related  events  are  update  and  activate.  An  update  event  occurs 
when  a  portion  of  a  window  on  the  screen  becomes  exposed  to  view.  This  happens 
when  the  window  is  t\vbit  created,  when  an  overlapping  window  is  moved  aside,  or 
when  the  window  is  enlarged. 

An  activate  event  occurs  wheti  a  window  bec-omes  active  or  inactive.  By  conven- 
tion, an  activf  window  i^  one  that  is  to  he  afFetled  by  subsequent  cominands  and 
drawing  operations.  The  active  witidow  is  highlighted  in  a  distinctive  way  on  the 
screen, 

To  determine  the  reason  lor  an  activate  event,  you  can  examine  a  bit  BaR  in  the 
Modtfiersi  flag  iif  the  event  record  returned  by  CelNextEvent-  if  the  bit  is  0,  the 
activate  event  ^ictually  corresponds  to  a  wiudow  beeooiing  inactive. 

Special  Events 

Most  of  the  events  nol  already  discussed  above  are  rarely  used  by  an  application. 
There  are  four  application-defined  events  an  application  can  post  in  the  queue  to 
report  a  custom  e%enl.  perhaps  the  occurrence  of  3  specific  combination  of  events. 

The  desk  accessory  event  oLcurs  when  a  user  enters  Co  n  tro  1-0  pen  Apple- Esc 
from  the  keyboard.  It  never  reported  to  the  application  by  GetNextEvent;  rather, 
it  is  trapped  by  the  operating  .system's  main  event-handling  routine  and  handled  by 
popping  up  die  Classic  De.5k  Accessory  menut  (the  one  containing  the  Control  Panel 
entry). 

A  switch  event  occurs  when  the  user  clicks  a  switcher  control  icon  to  transfer 
control  to  another  application  in  memory.  A  switcher  program  is  not  yet  availabSe 
for  the  cs,  however. 

A  driver  for  an  I/O  device  can  report  a  device  driver  event  when  it  has  reueived 
data.  ]t  may  aJso  reptirt  an  event  if  it  is  ready  to  send  data. 
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Figure  5-1,    Tlie  Event  Mask  Used  by  GctNextEvent  and  TaskMaster 


Bipplicetion  *4 

epplitstiari.  *3 

BppllCHtlDn  *Z 

device  driver  " 
desk  accessorij 
svitch   


Bctivate/deactivale 


IS 

14 

— r 

13 

12 

1 1 

10 

9 

8 

7 

B 

5 

4 

3 

2 

1 

a 

mill  evanl 

mouse  dsvr 
mouse  jp 

[reser^eal 
e  jto-  keij 
update 
I  reseryedl 


NfTl'l:,  An  i  vtnt  tjpe  is  seli'ttr'd  li  i1n  bit  is  1,  othL'twise  il  i5  ignored. 


GETNEXTEVENT  AND  THE  EVENT  LOOP 

The  Eveiil  Managtr  fiiiiL'tinn  Hiat  scans  the  event  queue  for  the  presence  of  an 
event  is  GetNextEvent.  (^ctNcxtEvent  returns  a  Booltfan  (true/fEilse)  jx-suJt  indicat- 
ing whether  tliere  wun  anything  in  the  queue.  If  the  queue  is  empty,  the  result  is 
fj]sc  (zeroj,  and  the  application  can  complete  the  event  loop  by  calling  GetNextEvent 
again, 

Mere  is  hnw  tn  call  GetNextEvent: 


PHA 

PuahWord  #(FFFF 
PuahPtr  EwentRec 
_Qiet  Neat  Even  1 
PLA 


jEpacE  for  result 
;event  maak 

jPointer  Id  event  record 
iPap  Boolean  result 


The  event  mask  tells  GetNextEvent  which  events  are  to  be  reported.  As  shown  Id 
figure  5-1,  each  hit  in  the  event  mask  word  uirresponds  to  a  particular  type  of 
event.  If  thf  bit  corresponding  to  an  event  i.s  J,  that  event  can  be  reported.  If  you 
are  interested  in  all  t\'pes  of  events,  pass  an  event  mask  iif  SFFFF  to  GetNextEvent. 

EventRec  is  a  16-byte  event  record,  GetNextEvent  fills  the  event  record  with 
infciimation  describing  the  event  it  removes  from  the  queue.  The  structure  of  an 
event  record  is  as  fbllaws: 
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Event  Gec 

ANQP 

wha  t 

DS 

2 

■,evBTil   gacte  (integer) 

DS 

4 

^euent  message  (long  uord) 

*hen 

DS 

4 

sticks   since  system  start up   (long  word) 

where 

DS 

4 

imcuae  pQ^itlon  {point) 

modifiers 

DS 

2 

jmodifier   fiag5    [ integer  > 

It  is  also  advisable  to  reserve  space  for  two  other  long  word  fields  immediately 
following  the  event  retard;  TaskData  iind  TaskMask.  They  are  used  by  the  Task- 
Master  fiinctioTi  (described  below),  not  by  GetNextEvent.  You  will  probably  use 
TaskMaster  more  often. 

The  What  Field 

The  What  field  of  the  rctiird  tuiitains  the  event  cude.  an  integer  from  0  to  15 
ideiitif>'iny  what  type  of  event  oeeurred: 


0 

null  event  (no  event  occurred) 

1 

inous{?-down  event 

2 

niousF-up  event 

3 

kev-doivn  eveiil 

4 

[not  used] 

5 

auto-key  event  (a  key  was  repeated) 

G 

window  update  event 

7 

[nut  used] 

8 

window  activate  event 

9 

switch  event 

1  0 

desk  accessory  event 

1  1 

device  driver  event 

1  2 

application -defined  event 

1  3 

application -defined  event 

1  4 

application -de  fined  event 

1  S 

application-defined  event 

Notice  that  two  cotHea  in  this  range,  4  and  7,  are  not  presently  defined.  On  the 
Mac-iiitosh,  an  event  code  of  4  corresponds  to  a  key-up  event. 

The  Message  Field 

The  Message  field  of  the  event  record  holds  a  4-byte  event  message  containing  more 
information  abont  the  event.  The  content  of  the  event  message  depends  on  the 
event  type: 
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mouse-tfnwn  button  niimlier  (0  or  1) 

inouae-up  biiflon  nunilier  [0  t)r  1} 

key-down  ASCII  cliaraoter  code  (0  to  127) 

aillo-key  ASCII  character  codr  (0  to  127) 

wiiiduw  update  Pointer  to  window 

window  activate  Pointer  to  window 

device  driver  Defined  by  the  device  driver 
applicatiQU-defined       Defined  by  the  application 

The  event  message  for  all  other  event  t>pes  is  undefined. 

The  When  Field 

The  Whfii  field  contains  the  time  when  tEie  event  took  place.  It  Is  expressed  in 
tickn  iince  system  atart-up.  A  tick  i:i  a  uiiil  of  time  eijual  to  one-sixtieth  of  a  second. 

The  Where  Field 

The  Where  field  holds;  the  vertical  and  horizontal  pn^ition  of  the  mouse  on  the 
■icrccil  when  the  event  nc^curred.  The  position  ts  calculated  usin^  the  global  cvor- 
dinate  system  In  this  etinrdinate  system,  the  origin  is  the  top  left-hand  comer  of 
the  screen  and  the  horizontal  and  vertical  axes  increase  to  the  right  and  down, 
respectively. 


The  Modifiers  Field 

The  last  field  in  an  event  record  holds  the  Jiuiclificr  j\ags  (see  figure  5-2),  These 
flags  indicate  the  jitatcs  of  the  keyboard  modifier  keys,  the  keypad,  "and  the  mouse 
iinttojis  vvlien  the  event  tonk  place, 

Modifier  kevi  arc  keys  that,  by  themselves,  do  not  generate  charatter  code.s  when 
you  press  them:  Shift.  Cups  Lock,  Control,  Option  (also  called  So  lid-Apple  J,  and 
t)pcn-Apple  (alio  cjallfd  Ct>miiiand),  An  applicition  will  inspect  the  modifier  flags 
if  it  is  designed  to  differentiate  between  events  that  take  place  when  a  modifier  key 
is  pressed  und  e^ents  that  arc  unmodified.  For  example,  an  application  might  want 
to  let  a  user  select  a  single  icon  by  clicking  a  mouse  button  over  that  iton,  or  it 
might  allow  the  user  to  select  a  group  of  icons  hy  clicking  the  mouse  button  over 
each  icon  while  holding  down  either  Shift  key.  When  such  an  appli<:atiijn  receives 
a  mouse-down  event  ftum  CetNextEvent,  it  would  check  the  modifiers  fielti  to  see 
ii  the  Shift  key  was  being  pre^.^edn 

The  flag  for  a  modifier  key  is  1  if  the  key  is  down,  and  0  if  it  is  up.  The  BtnOStale 
and  fltnlState  flags  behave  in  the  opposite  way — a  1  corresponds  to  a  button-up 
state. 
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Figure  5—2.     Tlie  Format  of  the  Modifiers  Field  of  an  Evi-nt  Ret-ord 
or  Task  Record 
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Twp  oth(;r  Hags  in  tht;  Modifiers  field  rclatt-  only  to  window  activate/deactivate 
events.  One  Hap,  AtliveFlag,  inditiites  whetlier  tlie  window  is  bem>;  activated  (J) 
or  deactivated  fO),  and  the  other  flag  indieates  whether  the  newly  activated  window 
is  of  a  diEerent  type  from  the  previously  aetive  window  {I)  or  whether  it  is  the  same 
type  (0).  {Windows  are  either  applieatioii  windows  or  system  windows.  System 
windows  are  those  created  by  New  Desk  Accessaries;  see  chapter  9.) 

The  Event  Loop 

The  eode  fur  a  simple  event  loop  is  remarkably  straightforward; 

EvtLoop  PHfl  -.Space  for  result 

PushWord  #*FrFF  ;Euent  maak:    all  everts 

PusliPtr   EventRet  ;Pointer   to  event  record 
_GetNBKtEvent 

PLA  jGet    the  HoBlean  result 

BEQ  EvtLoop  iBrancln   if   ng  ei/ent 

Until  an  c-vent  iit-turs,  the  code  between  EvtLoop  and  the  "BEQ  EvtLoop"  inslruc'- 
tion  is  executed  asain  and  again.  Thi*  is  heL-ause  the  result  is  always  false  (SOOOO], 
which  means  that  the  zero  fisg  is  set  after  the  PLA  Instruction.  When  an  event  is 
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reported,  the  result  is  true  (non-zero),  the  xcro  Rug  is  ulcarecl  hy  (he  PLA  instruction, 
and  control  passes  through  the  hottom  of  the  lotjp. 

The  code  following  the  lonp  L-ar  rcaii  the  event  type  code  from  the  What  field  of 
the  event  record  and  then  pass  ccmtrol  tu  the  suhrouline  that  handles  that  event 
t^TiCr  VtfTf  ii  an  example  uf  a  piece  of  code  that  does  just  that; 


LDA 

What 

;Get    event    type  cade 

^ISL 

A 

! Do able  it   to  get   tabic  offset 

TAX 

;Sct  up   indes   far   JMP  (addr,)!) 

JMP 

[tvtTahJe,)(J 

lJump  to  event  handler 

DC 

1  'Ignore' 

;Nuil  event 

DC 

1  '  DpPlou  5eDiiwn  ' 

DC 

I  ^DoriouseUp' 

;  Mou  ae-up 

DC 

1  f DoKeyDown  > 

;Kpy-dQuin 

DC 

I  *  J  gnore  * 

;  [ not  used ] 

DC 

I  '  Dotlou  aeDowTi ' 

;  flut  Q- key 

DC 

I '0oUpdat=' 

;MindDw  upclate 

DC 

I  ' ] gno rff  ' 

l[not  used] 

DC 

I 'DoflctivatE' 

;Nindow  activate 

DC 

I ' Ignore' 

1 5wi Ich 

DC 

I ' Ignore ' 

;Desk  flgg^ssory 

DC 

i ' DoDr 1 wer ' 

DC 

I  'DoflppH  ' 

;  flpp  1 1  cat  i  on-def  1  neiJ  #1 

DC 

I  'Doflppiai 

jfipplicfltion-titflfied  #2 

DC 

1  'Daftppl3 1 

;flpplication-defined  ^^3 

DC 

1 <DoAppl4i 

jfipplicfltion-defined  #^ 

JMP 

EvtLoop 

Notiee  how  this  technique  works.  The  entries  in  EvtTable  arf=  thp  addresses  of  the 
handlers  for  eacli  event  type,  in  evenl-t>T>e  order.  Because  eaeh  address  is  t^vo  bytes 
long,  tlie  entry  far  a  partiei.dar  event  is  at  an  offset  from  EvtTahle  equal  to  two  times 
the  event  type  code  value.  This  means  thul  yon  can  jump  to  the  handler  with  a 
JMP  (EvlTahle,X)  instruction,  when?  X  holds  the  offset. 

[f  the  application  deals  with  only  a  few  types  of  events,  it  may  be  more  convenient 
to  use  a  series  of  CMP  (compare)  Uistrtielloni^  to  route  the  application  to  the  proper 
event  handler.  Suppose,  for  e:tample,  an  applieation  handles  inOUSe-dowo  and  liey- 
down  e'vents  hut  ignores  everv  other  type  of  event.  You  euuld  pass  control  to  the 
two  event  handlers  using  a  code  fragment  like  this; 


LDfl  What 


;G&t  event   type  code 


CMP  #1 

eHE  CheckKD 

BRL  DaMDUseDDun 


its  It  rriouse-down? 
jNo,   so  bfBTTch 

;Ve5i   50  branch 


134    Event  Management 


CficckKD  CnP  #3 

BNE  [gnors 

BRL  DaKeyDown 


;  [s   it    k  ey-down? 
; No  ,    50  branch 
;Ye5,    sa  branch 


Ignore     JMP  EvtLonp  -.Bsck    to   the  evert  loop 

Notice  that  BRL  rather  than  BRA  instructions  are  used  to  hrandi  to  the  event- 
handling  subroutines.  Thifi  is  because  the  target  address  of  a  BKL  iiislniction  can 
btr  anywhere  in  the  64K  prosraiii  bank,  wherens  the  target  address  for  a  BR_r\ 
instnietion  is  restriuted  to  an  address  in  the  range  -12H  to  + 127  bytes  from  the  next 
inslructiun- 

If  GctNextEvent  returns  a  non-null  event,  it  automatically  removes  thp  event 
from  the  queue.  To  detenniiie  what  the  next  event  is  wilJioul  removing  the  event 
from  the  queue,  use  CventAvail: 

PHfl  ;5paceforre5ult 

PushWord  #IFFFF  ;event  masli 

Push Word  EventRec  jPainter   lo  event  record 
_Eveiit  flva  i  1 

PLfl  ;Boolean:al«iaystrLie 

After  calling  EventAvail.  informatiun  about  the  next  event  in  tlse  queue  can  he 
found  in  tjie  event  reeord. 

Before  entering  an  event  loop  at  the  bcginnin);  t>f  a  proKnun,  you  may  want  to 
remove  any  events  «'hicli  niay  be  lingering  in  the  event  (iiieue.  To  do  this,  call 
Flush  Events: 


PHA  ;spacG  for  result 

PushUgrd  #SFFFF  s  Even  t Mas  k   far  cvtnt  a   to  remove 

PuahUlord  #10000  ;SlDpMa5li   far  events  to  keep 

_FluahEwent5 

PLA  jflaak   for  first  event   not  removed 


The  first  mask  passed  to  FlushEveiits  descTibcf  the  types  of  events  that  arc  to  be 
removed  From  the  queue.  The  setoiiti  mask,  ealJed  StopMask,  describes  the  types 
of  events  that  are  to  stop  the  removal  process-  FlosbEvents  scans  the  queue  from 
the  beginning  and  removes  all  events  up  to  (hut  not  ineloding)'  any  event  described 
by  StopVlask  TKe  result  it  returns  is  the  mask  for  the  first  event  which  was  ntjt 
removed.  If  the  result  is  zero,  all  events  were  removed- 

In  most  cases  you  will  want  to  remove  even.'  event  from  the  queue-  To  do  this, 
use  an  EventMask  of  SFFFF  ajid  a  StopMask  oiE  StXXW.  as  in  the  example 


POSTING  EVENTS 

In  certain  situations  it  may  be  conVeoieut  to  place  events  in  the  event  (jueue 
yourself.  For  example,  yon  would  do  this  lo  pass  application -defined  events  lo  the 
system.  To  plate  an  event  io  the  queue,  call  PostEvent; 
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PHfl  ; apace  fat  result 

PuahUord  Event Cod»  ; The  eyenl  code 

PushLong  EventMag  ;The  e'jej^l  message 
_P05  tE\;e  nt 

pLfi  ;trut  =  eueril  was  pasted 


PostEvent  places  the  event  described  by  EventCocJe  and  EventMsp  in  the  cMent 
queue.  It  autonwliically  assifins  the  ciirrc^nt  time,  mouse  location,  and  state  uf  the 
modifier  keys  and  muiist:  button  to  the  other  fields  of  the  event  record.  There  is  an 
exception:  for  keyboard  or  jnouse  events,  the  modifiers  word  is  set  to  the  higb- 
order  word  of  EveiitMsg. 


HANDLING  EVENTS 

An  apphcalicin  mav  handle  an  event  any  way  it  wants  to,  of  course.  There  arc. 
however,  certain  ruleb  that  ever\'  application  should  follow  when  handling  events 
so  a.^  to  ffjnforin  to  Apple's  user-intierfaee  yiiidt lines.  This  section  explains  what 
these  rules  ^re  and  llow  tn  rcaet  in  .special  ways  to  mouse,  keyboard,  and  window 
events. 

Before  [iniceeding,  ii  commeiit  shonld  be  made  about  a  useful  fuactioii  that  is 
actually  part  of  the  Window  Manager,  nnt  tht-  Event  Manager:  TiiikMaster.  You  use 
it  uiuth  as  you  would  use  CetNextEvent,  the  difl'erenee  is  that  TaskMaster  prcieesses 
certain  events  ill  accordance  with  the  uj^er-interfaee  guidelines  before  rrtuminR 
contrul  to  the  caller.  This  allows  the  programmer  of  an  application  to  concentrate 
on  wrilin}^  code  iuii(|ue  to  the  application 

Here  is  an  event  loop  usijlg  Ta-^kXhister  instead  of  CJi^tNextEvejit: 

EvtLonp  PHfl  -.space   for  resuU 

PustnWord    *t%ffVV  lEvent  ma^k 

PiishPlr    Ta5kRec  ;Poinler    to    task  record 
_Ta  BfcMaa  ter 

PLfi  ;Poptheta5l<cc5de 

BEQ  EvtLoop  ?Br3nch   if    nothing   la  do 


Looks  flirailiar,  rif^ht? 

The  pro^rLuii  in  listinK  5-1  is  a  slniplc  prnpmm  shell  that  might  assist  ytjn  in 
developing  more  coniples  desktop  application?i.  At  its  core  is  a  simple  TfiskMaster 
even!  loo]i. 

The  task  reciirtl  referred  to  in  this  calling  setjuence  is  just  a  standard  event  record 
followed  l>y  kin^j  word  TaskData  and  TuskMask  fields. 

TaskData  is  a  long  word  in  wliiell  TaskMaster  sometimes  returns  a  result  {usually 
the  planter  to  a  window).  TiiskMask  is  a,  bit  vector  indicating  just  which  tasiks 
TaskMaster  is  to  handle  (see  Hpure  5^).  If  tlie  bit  lor  a  particular  task  is  0,  the 
event  code  Ibr  the  task  is  returned  jiisl  a.s  if  yim  hud  called  CetNestEvent.  It  is 
then  up  to  Ihe  applicati^m  tti  deal  with  it  in  an  appropriate  way,  In  most  cases,  you 
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Figure  5-3.    The  Formiit  of  the  Task  Mask  V^ed  fay  TjskMaster 
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^q^^E!  Bits  13  through  31  of  ihe  lask  mask  m>ist  be  £cn), 
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w-ill  want  TaskMaster  to  handlf*  everyihing  i\  is  dEsigticd  for,  sn  set  the  mask  to 
SOWKIIFFF. 

The  fimt  thinR  TaskMaster  does  is  call  CctNextEvpnt  to  get  an  tvf  nl  with  whicb 
it  eiin  v.■(^^k,  IF  then  deuls  with  the  e\  en\  in  a  standard  way  and  rctumi  n  task  tude; 
if  the  Lfidt-  is  0.  thene  i-i  riDlhiiig  iniire  for  the  application  to  do  and  it  f;in  Itmp  biiuk 
and  tall  TaskVJ^ater  a^ain. 

Assumini^  the  standard  task  mask  is  used,  TaskMastcr  may  return  the  following 
(.■(ides; 

1  nKey  [31        When  a  key  is  pressed  which  is  ncit  the  keyhoard  equiv- 

aleiil  of  A  menu  item 
inllpdate  [6J        When  ih*'  window  to  he  updated  does  not  have  au 

updatf  drawing  suhniutine;  see  ehiapter  6. 
wInMenuBar        (17)        Wh<.'n  a  mt-nu  item  is  seleL'ted  w  hieli  is  tiof  A  de&k 

iiecessor>  iti'ui  or  d  .'special  item  (viiidu,  eut,  copy,  paste, 

dear,  close);  see  chapter  7. 
wl  nContent        |19)       When  a  mouse-down  e^ent  otturs  in  the  content  re- 
gion of  the  Lietive  windi>w 
w  I  nGoftvuay         (22)      When  a  tnniiHe-dHwn  event  occurs  in  a  close  box  of  a 

window  and  the  button  is  released  in  the  close  box. 
wInSpecial       (25)      When  a  sptftinl  menu  item  is  selected  which  is  not 

accepted  by  a  desk  at'c-essor>' 
wl  nFrame  (27)       When  a  mouse-down  event  occurs  in  (he  frame  of  an 

active  window  (other  than  scroll  coiitrolsl' 

TaskMastcr  also  passes  through  mouie-up,  auto-key,  device  driver,  and  applicaition- 
dicfined  events  with  nti  pre-prrteesSinS  ul  ailV  kind. 

The  sections  that  follow  t^iver  ways  (o  handle  standard  Event  Manager  events. 
In  general,  the  descriptions  given  simply  describe  hnw  TaskMastcr  handler  the 
events.  There  an:  no  tipecial  requirenicnls  for  reacting  to  sv^itch,  device  driver,  and 
apph cat iDJi -de fined  events.  In  addition,  the  desk  accessory  event  is  handled  inter- 
nally by  the  Event  Manager, 

Mou^e-duwn 

When  a  mouic-down  evetit  acc\irs,  the  user  is  usually  seleetine;  an  object  on  the 
screen.  The  prof^ram  must  deterniilie  what  the  object  is — it  could  he  a  menu  bar» 
a  window,  a  scroll  control,  or  a  line  of  text,  for  example — and  then  process  the 
Selection  in  an  appropriate  way  before  rctnrnmE  to  the  main  event  loop,  Techniques 
for  handling  inuuse-down  events  will  be  dcstrihed  in  detail  in  chapters  6  and  7. 
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Mouse-up  events  arr  □ften  hai^dlcd  bv  tPTminaHnf-  an  aLtivUy  that  began  with  the 
previnus  mn.LSL-down  event.  Tht.  classic  example  such  a.i  activity  is  the  drawing 
of  an  object  the  scr^-eiv  while  the  mouse  button  is  down,  a  selected  object  follows 
the  cursor  around  the  screen;  wh.-n  the  button  is  released,  the  ob]cet  JS  released 
and  fixed  iu  plat^-  The  prograin  io  listing  5-'l.  For  example,  lets  you  size  a  rectangle 
by  drajieina  the  mouse  and  lettini!  RU-  ,      ■  , 

M.mse  up  events  mav  aho  he  handled  by  determhins  whether  the  button  was 
released  when  the  mouse  eursor  was  still  in  the  same  position  on  the  screen  as 
when  the  mouse  was  trst  pressed.  If  it  was  not,  the  appUcatiou  may  want  In  ignore 
the  mouse  dick.  For  example,  the  user  mterfiice  guidelines  insist  that  a  program 
isnore  a  mouse-down  event  in  the  close  or  zoom  bos  oi  a  window  if  the  button  is 
not  also  released  in  the  box.  The  rationale  for  this  dictun.  is  that  if  the  user  leaves 
the  vicinity  of  the  box,  be  iirobablv  wants  to  cancel  the  opertition. 

Another  operation  involving  a  mou.se-up  event  is  .  doiiblt^-click-the  pressing 
and  releasing  of  the  inouse  button  twice  in  quick  .succession,  A  double-;.litk  is 
frequently  used  tr>  shortcut  an  operation  that  normally  ret|liires  two  separate  clicks, 
such  as  the  launching  of  an  iippUcation  from  a  program  sector  utility  Two  consec- 
utive clicks  are  to  be  treated  as  a  double-click,  instead  of  as  two  unrelated  clicks,  il 
the  following  conditions  are  true:  the  time  (in  ticks)  lietwecn  the  mousc-up  event 
for  the  first  tlick  and  the  mouse-down  event  for  the  second  must  be  less  than  the 
DblTune  parameter;  and  both  clicks  must  take  place  within  the  same  object  or 
within  a  few  pixels  of  the  object. 

To  read  the  current  setting  of  the  DblTmie  parameter,  use  the  Event  Manager  s 

GetCblTime  function: 

PHfl  ;SpflCE  for   result    [long  word) 

PHfl 

.GetDblTlme 

PL(^  ;Pop  the  result 

STfl  DblTlne  ;  (low) 

PLfl 

STfl  DblTime*?       i  (high) 

The  default  value  for  DblTime  is  30  ticks,  hut  it  can  be  adjusted  using  the  es  s 
Control  Panel.  The  program  in  hsting  5-J  shows  how  to  detect  double  clicks,  when 
it  finds  one.  it  driiWS  a  small  black  box  on  the  screen. 

In  each  of  the  above  three  scenarios,  the  inoo^e-up  event  is  closely  related  to 
the  previous  monse^down  event.  For  this  reason,  mouse-up  events  are  best  handled 
during  the  processing  of  the  mousc-domi  event,  Mouse-down  events  that  occur  in 
the  main  event  loop  can  be  iRiiored. 
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In  the  hantllpr  fur  a  mouse-down  event,  use  the  Event  Manager's  SttllDowm 
fuTictinn  tt>  wait  for  a  mouse-up  event  ta  occur  so  that  you  fan  stop  dragging  an 
nbjiMTt.  checlk  (hat  the  mouse  is  still  in  an  action  box,  check  for  a  double-click,  or 
whatever.  Until  the  StillDwn  function  retunis  a  false  (zero)  result,  the  mouse 
button  is  itill  dowTi,  Ht'fe  is  the  calling  sequence  for  StillDovm; 


PHfl  ;5pace  for  Boolean  result 

PushUlord  #0  ;buttan  number    (always  0  tor  mousE) 

_St 1 1 IDown 

PLft  ?Pop  the  result 

BNE    ItaDown  ^Brarch   if    >t    i*  itlH  down 

BEQ   ItsUp  lB^at^ch  if    It    ia  up 


StillDowTi  docs  ncit  actually  remove  the  mouse-up  event  from  the  event  queue — 
GctNcxtEvcnt  takes  care  of  thai  when  you  return  to  the  event  loop.  If  you  prefer 
that  the  event  be  removed,  use  the  WaitMouseUp  funetion  instead  of  StillDown; 
in  all  other  respects  the  two  functions  work  the  same.  You  mi^t  wajit  to  use 
WaitMouseL'p  if  your  event  loop  does  not  i^ore  mouse-up  events. 


Key-down  and  Auto-tey 

An  application  should  react  to  a  key-diiwn  event  by  checking  to  see  if  it  corresponds 
to  the  keyboard  equivalent  of  a  menu  item  (this  is  covered  in  chapter  7).  Lf  it  is  not, 
there  is  no  standard  way  of  dealing  with  the  character — it  depends  on  the  apphcation. 
If  the  user  is  entering  a  line  of  text,  for  example,  the  program  should  display  the 
character  on  the  screen  and  update  the  active  cursor  position. 

Auto-key  events  are  usually  handled  in  the  same  way  as  Stey-down  events.  You 
may  want  to  ignore  then  tt  they  correspond  to  menu  itein  equivalents,  however, 
because  you  do  not  usually  want  commands  entered  from  menus  to  repeal  auto- 
matically. 

Window  Update 

An  update  event  oceurn  when  d  portion,  of  a  window  needs  to  be  redrawn.  Such  an 
event  occurs  in  the  following  !iitUL\tiotiS: 

•  When  tlie  window  first  appears  on  the  screen  (after  NewWindow  or 
Show  Window) 

•  When  an  overlapping  window  is  moved  aside  to  make  visible  a  new  portion 
of  the  window's  content  region 

■  When  the  window  is  enlarped  by  tugging  on  its  grow  bos 

•  When  a  portion  of  the  content  reginn  is  made  invalid  with  InvalHect  or 
hwalElgn 
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The  window's  update  region  defines  the  portion  nf  a  window  that  requires  rpdrawinR. 
This  may  be  the  entire  eContent  region  or  any  part  <jf  it.  Details  on  how  to  handle 
update  events  will  bt;  given  in  chapter  6- 


Winduw  Activate 

Window  activate  events  jigtiially  include  deactivate  events.  To  distinguish  between 
the  two^  examine  bit  0  af  the  Modifiers  field  of  the  event  record.  If  it  is  1,  it  is  an 
activate  event- 
Activate  events  are  handled  by  highlighting  the  window  and  bringing  it  to  the 
front  of  the  screen.  Highlighting  involves  drawing  racing  stripes  in  the  title  portion 
of  the  window  and  drawing  the  detailed  structure  of  stroll  mmtrols.  These  areas  in 
an  inactive  window  are  white. 

Activate  events  are  described  in  more  detaU  in  thapter  6, 


CURSORS 

Thp  eursc>r-handling  functions  are  actually  part  of  the  QuickDraw  tool  set  (see 
chapter  6)  but  it  is  appropriate  tu  discuss  them  here  beeause  they  arc  tied  to  a 
rather  common  user  activity  (although  not  an  event  handled  by  the  Event  Manager): 
moving  the  mouse.  A  cursor  i&  a  small  icon  that  moves  around  the  screen  as  VQU 
move  the  mouse  around  the  tabletop,  It  serves  to  inform  the  user  of  the  position  of 
the  mouse  on  the  screen. 

{A  program  can  determine  the  current  position  of  the  mouse  by  calling  GetMouse: 

PuahPlr    M(ju5ePo4ii      ;Ptr    to   space    for  result 
_Getf1t)ii9e 

iis 

(iQuaePosn     DS4  ^Position   in  localcoordinalffi 

Note  that  the  mouse  position  is  returned  in  the  local  coordinates  of  the  currently 
active  drawing  window.  See  the  next  chapter  for  a  discuiSiun  ol  local  coordinates.) 

The  standard  c\irsor  is  a  .■jniall  arrow.  To  make  it  visible,  call  InitCursor  (no 
parameters)  after  starting  up  QuickDraw.  You  cm  switch  to  a  custDm  cursor  using 
the  SetCuraor  function: 

PushPtr  TheCursor  ^Pointei-    to  cursor  record 

.SetCur  sor 

The  Cnir.sor  point.^  tu  a  cursor  record  that  defines  the  size  and  shape  of  the  cursor. 
The  structure  of  this  record  is  as  follows: 
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Cursor  height  (word) 
Cursor  width  {wind) 
CiHsur  iniape  (hytesl 
Cursor  mask  {fcytes) 
Hut  spilt  Y  [word]; 
f^Iot  spot  X  (word) 


iii  iflbt  of  cursor  r«tiiii^;le  in  rows 
Widlli  of  cursnr  rectantile  lii  word-t 
Cursor  clcfiiiilinn,  row  by  row 
Cursor  mask,  rmv  by  tuw 

Th<-  hot  spot  i?  the  positinn  in  the  rectangle  that  is 
aligned  with  the  muiisc  position 


Note  that  the  y^M  of  the  cursor  takes  into  account  the  "chimkine^s  of  the  ^rap\ncs 
screen  that  is,  whether  tw  (640-by-200  madcj  t  fnur  [320-hy-2(KJ  model  bits  a^e 
needed  to  define  a  dot  on  the  screen.  (Sereen  3resoluti«n  is  discussed  in  detail  m  the 
ne^t  chapter.  J  \«te  also  that  the  last  word  in  the  ^roup  of  words  dcRnmg  a  row  in  the 

cursor  must  be  xero,  , 

Tlif  cursor  mask  indieah-s  «  h,eh  parts  of  the  cursor  image  are  to  be  drawn  on  the 
screen.  OuW  these  bits  in  the  cursor  image  thai  correspond  to  1  bit*  m  the  t-ursor  mask 
are  u.ed  The  cursor  mask  .s  f-eiu-rally  a  filled-in  oiithTie  of  the  cursor  surrounded  by  a 
one-pixel  "slove. "  This  make,  die  cursor  visible  even  if  it  is  positioned  over  an  area  that 
lii  the  saiiif  color  as  the  cursor. 

Below  is  the  record  for  a  cursor  hi  320  finjphics  mode  (4  bits  per  paxel);  this  forms  an 
I-beam,  thf  standard  text-insertinu  cursor. 


DC 

DC 


,211  9  •  ;Height    [  ir*  piKP'  row9> 

ipni),  ;Uli(lth(in  word! ) 


DC  H'OOOCFrFOFFFOaOlJOl 

DC  H'ODOOOODFOOaOOODD' 

DC  HI  OOOODQOraOOOQQQil' 

DC  H'OOOOOODFOOOClOOOO' 

UC  HifiOOaOOQFQOOOCDDO' 

DC  H'CQOOOOOFOOCDOQaO' 

DC  n'oooooooFDaoaoooo' 

DC  H"  DoaooooFoooooooa' 

DC  H'QOOtlFFFOFFFODOOO' 

PC  H'ODDaOOOCOOCIOOOOO" 


OC  WOOOOFFFOFFFOOODD^ 

DC  ti'  OOOFFFFf  FFFFaOQO  ' 

DC  H'OOOOFFFFFFFOIjOOOi 

DC  HiOOOOOOFFFOOODOOD' 

DC  OOOOOOFFFOtJOOClOO' 

DC  H'OOOOOOFFFOOOOOOD' 

DC  H'DaOOOOFFFOOOOQafl' 

DC  H'QOOOaOFFFOOOOOOO' 

Oq  H'OOQDFFFFFFFOOCOD^ 


142     Ei  Piif  Mamsti.em*;ni 


DC 
DC 


H'ODOFFFFFFFFFOOOC 
H'ODOOFFFOFFFOOOOD' 


OC  I2'9,7'  ;HQt  spot   (baae  of  l-Beam} 

Yoii  can  locate  the  cursnr  rcixird!  for  the  ciirrctitly  at-tive  cursor  with  GetCursnrAdr: 

PHfl  iSpace  for  result 

PHfl 

_Ge ICursorfldr 

PopLong  CursorPtr  ;Pop  the  reault 

If  you  wish  to  switch  cursors  tempDrarilv.  use  GetCursnrAilr  to  get  the  pointt^r  to 
the  current  tursor  and  thc-n  use  the  pointer  when  restoring  the  cursor  v*1th  Stt- 
Cursur. 

If  you  want  to  remove  th*'  cursor  from  the  screen  for  Liny  reas^oti,  call  HidcCursor 
To  make  it  visible  again,  tall  SliowCursor.  N-Mthtr  fuiiLtiun  recjllirc=i  parameters  or 
Tetuniy  results. 

If  you  are  u,sing  a  cursor  to  itienlify  a  position  where  lext  nuiy  be  entered,  you 
may  waiil  to  make  tht^  ciirsor  blink  by  hidin);  and  showing  it  at  a  fixed  mte,  The 
blhik  rate  shnuld  be  the  wii*?  set  by  the  Ciintrol  Panel's  Cursor  Flash  command;  it 
can  be  read  using  the  CetCaretTiine  function: 

PHA  j'spaceforre^ult 
PHfl 

^GetCaretTime 
PopLong  CaretTiine 

The  Eons  result  is  expressed  in  ticks  [sixtieths  nf  a  second)-  The  default  Control 
Panel  setting  is  30  (half  a  setOnd), 

One  handy  cnrsm  fiinetiiin  is  ObscnreCnrsfir  It  removes  the  cursor  from  the 
screen  until  the  mnnse  moves.  Use  it  to  dimiiiate  the  mouse  cursor  while  a  user  is 
typing  somethtnf;  in  from  the  kf'vboard.  It  reiiiiires  no  paramctcr'v 

The  QuickDraw  Au\iliar>  loal  sel  contain.s  a  function  culled  WaitCursor  that  you 
can  use  to  chanRc  the  cursor  to  a  wristwatch  Vtm  ilioulJ  call  it  just  hfforc  perlorniing 
a  timc-consuminiL;  ojjcratinn  hi  inform  the  ui^er  th^l  the  program  will  ntJt  be  respond- 
ing to  input  fur  a  whiU?.  To  restore  the  arrow  eurscir,  call  hiitCursnr.  WailCursor 
requires  no  input  piirametersi  and  returns  no  reiults. 

To  start  up  the  QuickDraw  Auxiliary'  tool  set,  call  the  QDAuxStartup  function. 
To  shut  it  down,  call  QDAu.*iShutI5own,  Neither  luutrlioil  reijnirc:!;  parameters  nor 
returns  results. 
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A^;  mentioned  in.  chapter  1,  the  GS  h&S  4  bnik-in  floqlt/c-alcndar  chip  that  milmt^nS 
the  uurrent  time  ant)  date.  You  can  set  th^  current  time  and  date  with  the  Control 
Panel. 

One  Lommun  I/O  operation  (whifh,  like  mouse  movement,  is  not  handled  hy  the 
Event  ManaRerJ  is  reading  tlie  time  and  date  so  that  you  can  display  it  on  the  screen 
or  insert  it  in  a  printed  report.  The  Miscellaneous  Tool  Set  includes  two  functions 
you  can  use  to  read  the  eloek:  Ke-adAscitTime  and  ReadTimeHex. 

[The  start  up  and  shut  down  fiuiclions  for  the  Miscellaneous  Tool  Set  are  MTStart- 
iip  and  MTShutDown.  Neither  one  requires  parameters  nor  returns  results.) 

ReadAsciiTiine,  as  it^  name  suggests,  returns  a  20-byfe  ASCII-encoded  character 
string  describing  the  current  da'e  and  time.  To  call  it,  pass  a  pointer  to  a  previously- 
allocated  20-bytc  data  area; 

PuahPtr   TimtStrinC|  jPointer    ta   5trifig  area 

_Readfiac 1 1  Time  iRead  the  time 

RTS 

TimcString  DS       20  -.Spacs  for    time  string 

The  time  .string  is  not  preceded  by  a  length  byte.  It  is  always  exactly  20  characters 
lon^  and  the  high-order  bit  in  each  byte  is  set  to  one. 

Thf  string  returned  hy  RcadAsciiTimc  uses  nne  nf  three  date  formats  and  one  of 
two  time  forinats,  Altogether,  there  are  sis  formatting  combinations  (dd  =  day  of 
month,  MM  —  month,  yy  =  year,  hh  —  hours,  mm  —  minutes,  and     =  seconds); 

dd/MM/yy  tih:mm.;sa  XM  [KM    =    AH  or  PM) 

Mtl/dd/yy  tih:mm;ss  Xhl  flhis   ls  the  default) 

yy/PIM/dd  tih:mrBi:ss  ilM 

dd/MM/yy  hih;mm:5a  (2')-h{Jur  military  format) 

yy/MM/dd  titiimm:*! 

The  date  and  time  formats  actually  used  arc  those  set  by  the  Ckx-k  command  in  the 
Control  Panel. 

li  you  ikre  not  s.atisfied  with  the  look  oF  the  string  that  ReadAsciiTime  TetiirnS-, 
use  ReadTimellex  to  return  the  current  time  and  date  in  binary  form  and  then 
manipulate  the  data  ai  you  like.  Here  is  how  to  call  ReadTimeHex; 


PHA  jSpacefor  DayQf  Week /[unuaed]  by  tea 

PHA  ;Space  for  nor  t  h /DayOf  Plan  t  ti 

PHA  jEpace  for  Year/Hour 

PHA  sSpaceforPlinute/Second 


SeadTimeHex 
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SEP  #t?D 


iSwllch  to  9-blt   ft  for  hyte  data 


PLfl 

iPop 

Second 

STfl 

Second 

PLfl 

iPop 

Minute 

STA 

M  1  n  Li  t  e 

PLfl 

iPop 

Hour 

STf* 

Hour 

PLfl 

jPop 

Year 

STfl 

Year 

PLA 

;Pop 

Day  of 

Month 

STfl 

DayDf MOn Ih 

PLA 

1  Pop 

Month 

STfl 

Month 

PLA 

iPop 

u  nuaed 

byte 

PLA 

i  Pop 

Day  of 

STA 

DayQf  LUeek 

SEP 


iReturn  to  IG  blt  accLimu Ifl t □  r 


The  values  relumed  bv  ReadTimeHex  are  as  follows: 


FUNCTION  VALUE 

DayOfVVeek  1.  7  (l-Sutiday,  2-Mcniday,  etc) 

Year  0.  99  (Year  minus  1900) 

Month  0.  .11  (1  — Jauuarj',  2— Fphninry,  etc, 

DayOJMoiith  0.,30  (Day  ofuiifTith  minus  1) 

Hours  0.23 

Minutes  0-59 

Seconds  0.,59 


Remember  that  ReadTimcHcx  was  the  fiinction  used  by  the  user-defined  TitneTocjU 
tool  set  in  chapter  3  to  determine  the  day  of  the  week  code  prior  to  converting  it  to  a 
text  string. 

One  other  usehd  time-related  ftinction  is  TickCount.  Use  it  to  determine  the  number 
of  ticks  ttiat  hsvc  elapsrd  since  the  GS  was  started  up  (a  tick  is  l/60th  of  a  seccmd)  . 
Here  is  how  to  call  TickCount: 

PHfl  ;  Spec  e  for  long  result 

PHfl 

_T  1  c  k  Coun  t 

P  op  Lo  ng  NuimT  lcJis  iPop   the  result 
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To  put  a  delay  hop  in  a  program,  call  TickCnunt  oncp  before  eiitermg  the  loop  and 
then  keep  calling  it  until  the  diHtrrence  between  the  result  and  the  starting  value  is 
j^redter  than  or  equal  to  th*-  desired  delay. 

To  generate  a  two-second  (120-tick)  delay,  far  example,  use  the  Following  code 
fragment; 


PHA 

PHft 

_Tic  kCouTit 
PopLong  TickStart 


jGel   atartlTig   licl  cotint 


D^layLoop  PHfl 
PHft 

_T;cl<CoLinI 
PopLong  TickCurr 


;Get   currcnl    tick  count 


sec 

LDA 
SBC 
STA 
LDfl 
SBC 
STft 


iCalculste  tiptie  difference 


TickCurr 
TichStart 

T 1 c I Cu  r r 
TicrCurr+2 
T 1  c  fc  S I  □  r  t -(■  0 
TickCurr+2 


SEC 
LDft 

LDA 
SBC 


T 1  c  t  Cur  r 
#120 

TickCurr+2 
#0 


-.Subtract    120  tlong) 


BCC  DelsyLoop 


incti   if  <  120 


RTS 


TlckEtarl  DS 
TickCurr  DS 


Notice  that  the  carry  flag,  which  is*  set  before  a  subtraction  operation,  becomes  dear 
if  thf  iKimhcT  heinf:  suhlracted  is  greater  than  or  equal  to  the  number  in  the 
iiLcu[iiulator+ 
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REFERENCE  SECTION 

Tabk  The  Major  Functions  in  the  Event  \taiia8er  Tool  Set  ($06) 


Function  Nams 


Button 


EM^tiirtup 


EMShutDnwn 
Even  [Avail 


FlushEveQts 


GetCaretTimc 
GetDhlTime 
Gel  Mouse 
Get  Next  Eve  lit 


Fit  nrtinn 
Ssimhi'f 

SOD 


$03 
$0B 


SIS 


S12 
Sll 

$0A 


Stack 

Pfirajtieters 
result  (W) 
ButtonNiim  (W) 
DPAdcIf  (W) 
QueueSize  (W) 
XMinCkinp  (WJ 
XMaxCUmp  I\V) 
YMinClamp  (W) 
YMaxClump  (W) 
UserlD  [W] 
[no  paramelersl 
result  (W) 
EvcntMask  (W) 
EveiitRecord  {D 
result  (W) 
EveiitMask  (W) 
Sti)i)Miisk(W) 
result  {D 
result  [L) 
MHUscLtKiPtr  iU 
result 

EventMflsk  {W) 
EventRecord  (Ll 


Description  of 
Parameler 


Buolean;  is  the  button  downf* 
Button  niiinber 
Address  of  1  page  in  bank  0 
Size  of  event  queue 
Mnuse  miniinurn  (horizontal) 
Mouse  maximuin  Oit>rizontal} 
Mouse  minimum  (vqrtica.1] 
Mouse  maximum  (vertical) 
ID  tag  fur  memor>'  allocation 

Boolean:  always  true 

Event  mask 

Ptr  to  event  record 

Muhk  for  next  event  in  queue 

Mask  for  events  to  he  flushed 

Mask^  for  events  to  he  kept 

Ticks  between  cursor  blinks 

Inter\'a]  for  doiible-clicks 

Ptr  to  mouse-  point  ilocal) 

B(Kile;m:  was  event  retrieved? 

Event  mask 

Pti"  tu  space  for  cvqrnt  record 
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Function  Name 


PoslEveiit 


StillDown 


Function 
Number 


$14 


SOE 


TickCoimt  SIO 
WaitMoiiseUp  SOF 


Stack 

Parameters 


result  <Wl 
EveiitCode  (Wl 
EventMsg  (L) 

result  (W) 
ButtonNum  [W) 
result  (L) 
result  (W) 
BurtonNum  (W) 


Df.'ichpiion  of 
Parameter 


Booieilii:  was  event  imsted? 

Event  code  t(t  pluqr  in  queue 

Message  w(ird  fnr  event 
reL-ord 

Boolt^an:  Ituttiin  stiU  do\^Tl? 
Bulkiii  number 
Ticks  sinee  Kysteni  startup 
Boolean:  buttun  sKi\]  down? 
BuLtOn  number 


Table  R5— 2;     Event  Manager  Errnr  Oodrs 


Error 


Code  Description  of  Error  Coiiiiitian  

S0601  Tlie  Event  Manager  has  aJready  been  started  up, 

$0602  Reset  error. 

S06O3  The  Event  Manager  is  not  active, 

$0604  The  event  code  is  greater  than  15. 

$0005  The  specified  button  number  is  not  0  or  1. 

$0606  The  size  of  the  event  queue  is  greater  than  3639. 

$0607  There  is  not  enouf^h  memnr}-  for  the  event 

queue. 

$0681  The  event  queue  is  seriously  damaged. 

$0682  The  handle  to  the  event  queue  is  damaiged, 
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Tabic  R5-3!     Useful  FunLtions  in  the  Window  Manager  Tool  Set  ($QE; 


Functiiiti  iVajne 


Fzinciiou 
Number 


Task  Master 


$1D 


Stack 

Parameters 


result  (W) 
EventMask  (Wl 
TaikRccord  (L) 


Description  of 
Parameter 


Event  code 
Event  mask 

Ptr  to  space  for  task  rttord 


Table  R5-4:     Useful  Functions  in  ihe  QiiitrkDraw  H  Tni»l  Set  (S04) 


Functiun 

Stack 

Description  of 

function  Name 

Number 

Parameters 

Paratieter 

GetCursorAflr 

S8F 

result  (L) 

ptr  to  cursor  record 

HideCursor 

$90 

[no  parameters] 

InitCursor 

*CA 

[no  parameters] 

ObscureCursor 

$92 

[no  parameters] 

SetCursor 

SSE 

CursorRecord  [U 

ptr  to  L-ursor  record 

ShowCursor 

$91 

[no  parameters] 

Table  R5-5:  Useful 

Functions  in  th 

c  QuickDraw  Auxiliar>-  Tool  Set  {S12) 

Function 

Slack 

Description  of 

Function  Name 

Number 

Parameters 

Parameter 

QDAnxShutDowii 

$03 

[no  parameters] 

QDAuxStartup 

$02 

[no  paminetersl 

WaitCursnr 

30A 

[no  parameters] 

Table  RS-d:     Useful  FuRctiuns  in  the  Miscellaneouf;  Tho!  Set  ($03)_ 

Punction       ifiiefc                     Descriptiori  of 
Function  Name       Number        Parameters  Parameter 

MTShutDown         S03  [iio  parameters] 

MTStartup  $02  [no  parameters] 
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Function  Name 
HeadAsciiTimc 

ReadTimeHex 


Function 
Number 


«0D 


Stack 

Parameter.^ 


TimeString  (L) 
result  (W) 
result  (W) 
result  (W) 
result  (W) 


Description  of 
Parameter 


Ptr  to  20'byte  time  string 
Day  of  week  (high  byte) 
Month  (high)r  date  (Iqw) 
Yeilr-1900  (high).  Hour  (low) 
Minute  (high).  Second  (low) 
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listing  5-1;     A  Program  for  Assisting  in  the  Develop inent  of  Other  Programs 


•  You  can  u^e  thia  prografti  sa  a  ahelJ.  • 

•  for  writitig  B  complete  OS  appl  Ic^  I  ion-  " 


LIST  OFF 
ABSflDDR  QN 
IMSTIME  UN 
OEN  OFF 
SYMBOL  OFF 


flCQPV 


SHELL 
SHELL. nAC 


J  Qbj  «c I  code  file 
; Ma era  file 


riyCodc 


START 


ClotjolData 
Start  Data 


J5R 


;$tart  Lip  ail   tool  aeta 


;  De-fine  and  display  the  menu  bai": 


PuahLorg  'Q 
PushPtr  MeriLjLE 
_MewMenu 
PiiahUord  '0 
.Insert Menu 

PuahLoTig  '0 
PushPtr  MenuL! 
_Ne'wMBnu 
PushWord  /O 
_l  naer  tMcTiu 

PuahWord  '1 

_FtiiftppleHemi  lAiid  desk  accessoriea   to  menu 


_F  IsflenyB^r 

PLP1 


^Adjust   3lie  0*  m-enu^/menu  bar 


DrfiurMenuSsr 


J  Define  and  display   the  window: 


PHfl 
PHA 

PuahPtr  MsinUirdoiM 
NewHlndoM 


;  Spac  p   for  reault 


jPointer  lo  window  record 
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PopLong  WmdowPlr 
_ 1 r  t  tCur  5flr 


jEave  pointer  to  window  record 
jTurn  on  the  arrow  cursor 


EvtLoop  PHfi 

pLiBhWord  i-lFFFF 
PushPtr  EventRec 
T&5  kMp|9  Isr 


; Al 1 ou  all  event s 


PLfl 
CMP 

BEO 


*v  1  rPIt  nuBar 
DoMenu 


: Oe  t   reau 1 1  code 
;Meiiu    irtent  selected^ 
;  Ye □  ,    5  D  branch 


;    [check    for   other   everta  hereJ 
BRL  EvtLocp 


iBact  for  more 


;  Handle  mtru  item  ^electiors.  (The  item?  must  be 
1    numbered  aequent  ia  1  1  y  frcam  25G,) 


DoWenii 


LDA 
SEC 
5BC 
RSL 
TAX 


T&  5  V  Data 
A 

(MeiiiaTablc ,  t } 


;  &et  mcTiLi  Item  ID 

; Convert  to  D  baa e 

La  4t«p  into  table 


Pushklord  #0 
Pii5h.Word  Taa1tData-t2 
_H  1  1  1 t cMcng 


jHighlighllrg  off 
;Gel  merLi  ID 


DBA  EvtLoQp 
;   Table  of  menu  item  ^kibroutire  addresses: 


MervuTable  DC 
DC 

; 


DoAboLit  I 
DoQui  t  1 


DC 

BIS 

PLfl 
JMP 


I  'DoAboLit  [  I 

I  'DoQuit  I  ■ 

I  ' DoVDur I  tern' 


DoShu  tDowr 


Item  25e 
Item  257 

I  tern  2^3    ...    a  nd  a  o  cn 


;P[>p    retu.rti  addres'S 
;Shut  down  all  tool  sct^ 


END 

CQPY 
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GlobolDala  OflTft 


lists,    if  you  add  more  items 

,   number  them 

;  conaecii t  ively 

f  f  om 

25S. 

DC 

C 

iApple  ncTiLi 

DC 

C 

"About   this  program 

\N25GVi ,H'OD' 

Meruit 

DC 

c 

>>  Flic   \N?' ,H'&D' 

;F  1  le  menu 

DC 

c 

^'QultNHSBJ-Qq'  .fi'OD 

DC 

c 

:ETid 

of  menu 

I     iiJ  k  Ti  ei  i^uf 
1     ni  J  II     y  w 

p3  rameter  s : 

WmdowPl 

r  D5 

4 

;  Painter 

to  uindoif 

MyTitle 

STB 

GS  App llcaliqn  ' 

Mb  i     i  n  d 

aw  DC 

l£ 

'UindErd-MainUIiridow' 

DC 

1  1 

t1 OOOCDOOl 0?  Q01 Ql  • 

;  w  1  n-dow  frame  deflmition 

DC 

M 

'HyTitle' 

^Pointer    to  window  title 

de 

■0" 

1 ref con 

DC 

I  1 

0.0,0,0' 

;zOGm  rectanglei 

DC 

M 

'0' 

icolor  table 

DC 

1  ' 

O.S' 

icrigLH  o-ff'iel 

DC 

1  1 

0.0' 

; height ,w 1 d t h  dale  area 

DC 

1  1 

0.0' 

j  he  Lghl ,  u-i  d  t  h  msic  uindow 

DC 

I  1 

0.0' 

;  ver  t ,  hor  iz  scroll 

DC 

I  ' 

0,0' 

i  ver  t ,    har 1 z  page 

DC 

H 

'0' 

i 1 nf Q  bar   ref con 

DC 

14 

■  fl- 

i  f  rame  def  pr  o  c 

DC 

H 

■  o- 

; 1 nf 0  bar   def proc 

DC 

\Z 

"0" 

i 1 nf o  bar  height 

DC 

14 

1  [[  1 

jcontent  defproc 

DC 

T  1 

30  ,1  0  ,  1  95  .400  > 

;CQnlpri[   region  rectangl 

DC 

14 

'-1  1 

}flt   the  front 

DC 

14 

'0' 

;  Storage 

ANDP 

EvenlRcc 

ANCP 

Uhat 

D5 

2 

Message 

DS 

4 

DS 

4 

Uhere 

DS 

4 

Hod  i  f ler  5 

DS 

2 

TeakDota 

DS 

4 

"tas  k  riaak 

DC 

14 

;EveTit  code 

;Event  result 

iTickB   since  startup 

1  Mo  Li -SB  locatLOTi  (global) 

;5tatus  of  modifief  ley% 

jTaskria^ler  d£it^ 


H'taOOOIFFF' 


END 
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Listing  5-2:     A  Program  Showing  How  to  Use  SMllDiivvn  and  GelMoiisc 


*  This  program  shous  how  to  use  Ihe 

*  StillDowTi  and  GelMouse  functiona.  By 

*  pulling  cn  the  mouse  with  the  button 

*  down,   you  can  create  ^   rect^ingle  of 

*  any  a i 2e . 

LIST  OFF 
AB5ADDR  UH 
INSTIME  DN 
GEN  OFF 
SYMBOL  OFF 


KEEP 

Mcopy 


DRAG 


;  Gb J  ec  t  code  file 

■jMacrg  file 


STflfiT 
Us  1  ng 

JSR 


ClobalData 
DoStar  tup 


i  Define  and  di^pl^y  the  ii^indow'; 


PushLong  ''0 
PushPtr  nainWiiKJow 

_Stflr  t Drawing 


iSpace    for  result 
jPoinrter   to  window  record 

;Prepare   to  draw  in  window 


IritCurSor 


EvtLoop 


Exit 


PHfl 

P(i?hWQ(-d  /tFFFF 
PushPlr  EventRec 
Ta 3 1 5  t  pr 


;flll  events 


PLfi 

■,Qet  result  cotie 

CMP 
BFQ 

'  1:  cyDoMnEv  t 
Exit 

;  Key -down? 

;  Ves ,    30  branch 

CMP 

BNE 

VwrnContent 
EvtLoop 

;  in  content  region? 
;iio,    50  ignore 

JSS 
GSA 

DoBo 1*5 
EvtLoop 

JMP 

DoShu  tDown 

END 
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;  Display  a  box  on  the  screen.  i-t  using 

1  dragging  techniques, 

OdBoxps  start 

Using  GlabalDala 
Pu^hPtr  Where 

_G lobalToLocal  ;ci)rivert   to  window  coords 

•-,   Jnitlal    rectangle    is  a   single  pixel: 

LDA  Whcre+h 

STA  BoxRect-^laf  t 

STA  BoxRect+right 

LDA  Where*v 

STA  BgjcRect'^top 

STA  BoKRec  t  *bot  t  Din 


Slretchlt     PushPtr  BoxRect 
_I nvpr IRecl 

Strctchltl  PHft 

PushWord  '0 
_St 1 1  IDown 
PLft 

BEQ  DragExi  t 

Pu5hPIr  MoitatLoc 
OetMouae 


;draw  the  new  rectargle 

jspace  for  result 
;  [noLj.3 1  bu  1 1 on 


^branch  if  not  still  down 

;tjet  curreTit  mouae  positic 

;    (local  coords) 


;  If  current  location  la  aome  as  last  one,  3d  Tiothing.  This 
i  avotdig  estcesaive  flashing  an  the  screen. 


Sa veLoc 


LDA 
CMP 
BNE 
LDA 

BEQ 

LDf\ 

LDA 

STfl 


Mqu seL Dt  * h 
La  atLoe*  h 
SaveLoc 
f\au  seLoc  ♦  V 
LaatLoc 's/ 
Strelchltl 

MDLiaeLoc*h 
Last  Lac  t^h 

Mo  LIS  cLd-c  +  V 
Last  Loc  *v 


;HDri2ontfll  matches? 
;Ncii   90  brancli 

iVertlcal  matches"' 
jYea,    so  branc-h 

;Sav^  th^  riew  position 


PushPlr  BoRect 
_I nver t Rcc  t 


;erase  the  old  rectarigle 


;  Arrange  coordinates  of  the  new  rectanglp  in  the 
;    s  ta  ndar  d  top,    leftj   bottom,    right    (TLBR)  order;. 
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LDfl 
CMP 
BCC 


MouscLoc+h 

_1 


l5  horljontal  pgsltion 

to  the  ieft  of  the  biBiB  poirt? 
Yes,    40  branch 


5Tfl  BoKRect*right 

LDft  Whtre+h 

ETA  Boifiecl*lef I 

BRA  2 


-2 


STfl  BoKP^clMef  t 

LDA  Where'h 

STA  BoicRect^right 

LDfl  flou  seLoc*v 

CMP  Where*v 

BCC  _3 


;  1 3  ntw  vertical  positLori 
;  above  the  base  point? 
I  Ye  s ,   so  branch 


STA  Box Gtct+bol torn 

LDA  Where'v 

&TA  BoxRec  t  *  top 

BRL  Strelchit 


STA  QoxRectttop 

LDfl  Where*v 

STft  BoxRec  t  *ho  t  tom 

BRL  Stretchrt 


DragEji  i  X  RTS 


END 


CDPV         STANDARD. ASM 


GlobalData  DATA 


;    Ui.ndow  parameters; 


RyTlUe        STR  '  Drag  Demo 


DC 

la'WindETid-riainWindow' 

DC 

1 ■ 31 oaooo ' 

title    bar  only 

DC 

H iMyTitle^ 

iPointer   to  window  Lktle 

dc 

]4'0' 

~,  ref  con 

DC 

1  '0,0  ,a  ,0 ' 

J  zoom  r ec  t  a  ngie 

DC 

I4'0' 

jcclor  table 

DC 

1  '0.0  ' 

;lTiitial    origirt  offset 

DC 

P  0  ,0  ' 

1  hei gh t , width  data  area 

DC 

n  0 ,  a ' 

;  hei ght , width  max  window 

DC 

PC  ,0' 

; ver  t ,    hori i  line 

DC 

1  '0,0' 

;  vcr  t  ,    horn  p'agft 

DC 

;  1  hf  0  bar  r cf con 
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DC 

(  1     □  bar  height 

DC 

14"  a ' 

DC 

H  t  Q  ' 

5  1  nf 0  bar   de  f pr  oc 

DC 

M'O' 

; content  defproc 

DC 

1  <30 .1  Q ,I85,50D' 

jContent   region  rectongle 

DC 

;iAt    the  froTit 

DC 

!  Storage 

UjndEnd 

ftNDP 

MdusbLoc 

DS 

4 

;a  point 

BoxRec  t 

DS 

8 

jCoordiriBles  of    stretched  reclangle 

LastLoc 

DS 

1 

; a  po 1 r  t 

EventRec 

ANQP 

Mhat 

DS 

■,£verit  code 

05 

•I 

;Event  result 

DS 

;Ticka   since  startup 

WherE 

D5 

4 

;MotJ9e   location  (global) 

Modi f 1  era 

DS 

;St^tus  of  modifier  iey^ 

DS 

4 

;Ta5 t Mas ter  data 

DC 

il'OOOOIFFFt 

EHB 

Lisling  5-3:     A  frogrsm  Showing  How  to  Use  C^etDblTinn:-  ami  WaitMnusel^p 


■•  This  prograrn  5hc)*s   how  to  detect 
*  □peration^   When  you  doub t e ■ c 1 l c 
■   black   rectangle  on   th&  screen. 


a  doub le-c lici 
,    1 1   displays  a 


riyCode 


LIST 

OFF 

SVMBDL 

OFF 

AQSADDR 

ON 

JNSTIME 

□  N 

GEN 

□  H 

KEEP 

DOUBLE 

MCDPY 

DOUBLE.nflC 

START 

1  ng 

CLobalDatd 

Using 

StarlData 

JSR 

DoStartUp 

; Qbj  Bc  t  code  f 1 1  a 
jMacro  file 


;  Define  and  display  the  window: 
ShowWind 

PHfl 

PushPtr     Ma inWl ndow 
NewUiTido*' 


;  Space   for   reSLil  t 
sPointer    to  window  record 
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Pa pLo ng   UindawPl r  ;Sflve  pointer    to   wiridow  retflrd 

_l  nit  Cursor 
EvtLoop  PHfl 


Pti  shWor 

d  #«FfFF 

:  Al  1 

euen  t  a 

Pti5hPtf 

Ta5.tRec 

_Ta5  kf^a^ter 

PLfl 

;  Get 

result  code 

CMP 

•  *  eyDownEvt 

;Key 

-dawn  f 

BEQ 

Exit 

;  Vea 

,    so  branch 

CMP 

'w\ nContent 

;  i  n 

content  region? 

BNE 

'E  u  t  L  0  o  p 

;  ID  1 

^(3  ignor-e 

JSR 

DoClicfc 

HRfl 

E V  t  Loop 

JMP 

DoShu  tDouTi 

END 

Check    far   a  don b  I  b  -  c  1  i  c t . 


If  it's  a  double  clicks  display  a  rectangle 
filled  with  the  pen  pattern. 


noClick  5TART 

Usirg  ClobalData 

PuahLcng  UindowPtr 
_S t ar  t  Drawi ng 

PHA 
PHfl 

.GetDblTime 
PopLoiTg  DblTime 

PushPtr  Where 
01  obs 1 ToLccd 1 


■[Prepare  to  draw  in  wjndau' 

;Space  for  result 

;get   da  uh  1  e -c  1 1  c  It  tline 


iConvert  mouae-doi^n  location 
1    to  window  coo''d;nate5 


;  Calculate  time  since  last  mouse-up: 


SFC 

LDA 

Uhen 

5BC 

LfpTime 

STA 

TbeGap 

LDA 

Whe  n  +  2 

5BC 

UpTimetS 

STA 

TheGep'-2 
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J  Ch«ci    the  mouse-up   /  mousE -down  irterval; 


SEC 
LDA 
SBC 
LDA 

sgc 

BCS 


DblTime 

TI-ieCs|i 

DblTimt*2 

ThtGap*? 

Doubled 


■;  bran 


;  Wail   unlil   mouie  button   is   releasedj    then  save   t  ime: 


UeitforUp  PH.A 

Pii5hWard  "0 
_Uia  i  triDLiae-Up 
PLfi 

BHE  UaitForUp 

PHA 
PHfi 

_Tlcl(CDunt 
PopLong  UpTime 
RTS 


; space  for  result 
jniouse  button  ('0} 

jWait    for    the  following  mou^e-up  event 
jGet  Booieari  result 
;Loop  until  moLiSie   is  up 

'^ipace  for  result 

;Get   curr-enl   lick  count 
;Get   tht  result 


5  hie  had  a  doub  1  e-e  1 1 ct  ,  so  draw  a  solid  rectangle: 
Doubled  l^HQP 


etc 

LDA 

STA 
ADC 
STfi 
CLC 
LDA 
STA 
ADC 
STft 


Where*  h 
OurBox+ left 
#30 

□  urBoK ' r  i  ghl 

Ulher  c  'v/ 
OurBox+ 1  op 
.rlO 

□  iirBDX*bottom 


PuahPt  r  OurBon 
PaintHect 


;Drflw  the  solid  hoc 


DblTlme 
UpTlme 

TheOap 
On  rBox 


RTS 

DS 

DC 

1410 

DS 

<) 

D5 

S 

END 

LONG  (dpiihle-cUcl:  time} 
1 1  me  of    last   mouse -up 
up-down   time  gap 
Rectangle 
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CaPV         STftNDftRD. ASM 


GlabalData  DftTfl 

;   Ulrdow  parametEra: 

WindowPtr     D5  4  ;pDiTiter  to  window  record 


riyTit  le 


5TR 


Qoublf -C 1 1  c I:  Demo 


MBlnHindow  DC 
DC 
DC 
DC 
DC 
I>C 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 

WirdEnd  flNDP 


12'Wi.TidEiid-MainWindow' 
1 "X1 1 01 1 1 01 1 01 00IO1 ' 
14'HyTiIle' 
M'O' 

I  '0,0,0,0 ' 
14'0' 
I  '0,0' 
I  '0,Q' 
1  '0,0' 
1  'D.Q' 
I  ,0' 
If-  0 ' 
I2'0' 
I4'0' 
]4'0' 
]4'0' 

I '31  ,G. 132, 608' 

H'  -1  + 

II' 


iBlze  of  lahlE 

; wi r  dou  f  rame  type 

;Polnter  Id  window  title 

I  r  ef  con 

;  zoom  rec  targ le 
jcolor    table    (0    -  default) 
idocument  offset 
iheighl, width  of   data  area 
; height ^width  man  window 
;vert,    horii    line-  movement 
ivert,    harli   pagt  movememl 
;  1  rf □  bar   ref ccn 
liirfo  bar  height 
;-tramc  defproc    (0    =  atanriarc 
Iiirfc    bar  defproC; 
;  coTit  cnt   def  proc 
; Content   re^L-on  rectaTi^Ie 
;tii   the  front 
tStor-agp   (me  MM) 


jTaskHealer    ta^fc  recorij; 


ANOP 

Uhat 

DS 

£ 

Event  cade 

lies  sage 

DS 

4 

Event  resu 1 t 

Uhen 

DS 

4 

Ticks  since  star  tup 

Uhere 

DS 

4 

nouse   locfitkan  (globaO 

Modif icr  a 

DE 

2 

Status  of  modifier  keys 

TaskDa 1  a 

DS 

A 

Ta  5  i  fla  5 1  er  datfl 

TaskHa  aik 

DC 

MHOODOIFFF' 

TaskMaater   handler  ali 

END 
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CHAPTER  6 


Windows  and 
Graphics 


This  chapter,  and  the  three  that  ftilkiw,  esamine  ways  to  develop  applications  thdt 
use  the  cs's  super  hish-resolutinn  graphics  scrt'cn  tii  a  Macintosh -like  deAktnp.  Tht 
discushioii  will  hc'pn  willi  an  annlysis  windows  ;iiiJ  tlieii  will  mtwt-  ofi  to  pull- 
down menus,  ditilng  and  alert  biixes.  and  finally  desk  accessories.  The  GS  has  tool 
sets  for  dealing  with  all  thes*-  standartl  desktop  features. 

A  window  Im  an  object  on  the  desktop  that  at-ts  as  the  private  display  screen  for 
a  single  docmnetit  The  underK  inn  dwument  may  be  a  series  of  lines  of  text  or  any 
arbilrary  graphic  iinsEjr.  and  it  may  \w  liny  size.  If  the  underlying  doeument  is 
larger  than  the  portioiii  of  the  window  in  which  drawing  operations  appear  [called 
the  content  ref;ion),  however,  not  all  of  it  can  he  seen  at  once.  To  permit  the  viewing 
of  any  portion  of  a  larRe  docunient.  you  can  add  holtoni  and  right  scroll  qcmtrols  to 
a  w'indc}w.  By  adjusting  these  tiaiUrols,  it  is  possihlc  to  move  any  portion  of  the 
document  into  the  content  region. 

The  cs  handles  windows  in  a  flexible  way.  You  can  define  as  many  windows  as 
mcmiin,-  permits  and  you  caji  display  thein  all  on  the-  screen  at  once.  A  window  is 
tntallv  independent  of  any  other  windtfw.  so  it  can  appear  aiiy^vhere  on  the  screen, 
even  thoufih  it  inav  overlap  or  totally  obscure  another  window.  Some  windows  are 
re-sizahle  and  some  may  be  dragged  around  the  screen  with  the  mouiie. 

By  convention,  the  frontmost  window  is  the  active  window,  the  one  that  will  be 
affected  by  drawing  operations;  other  window's  are  said  to  be  inactive.  The  active 
window  is  drawn  in  a  distinctive  way.  with  a  solid  block  in  the  title  bar  and 
hijjhlifihted  st  roll  controls.  This  di,>itinguishes  it  from  inactive  windows,  which  show 
onlv  the  outlines  of  the  scroll  controls  and  title  bar. 

Tins  chapter  cm  ers  how  the  Window  Manager  (tool  set  14)  can  be  used  to  create 
various  types  of  windows  and  to  display  them  on  the  screen.  Changing  the  size  and 
appearance  of  windows,  mnvin^;  windows  around  the  screen,  handling  windows  that 
have  scroll  controls,  and  dealinj^  with  multiple  windows  arc  dso  discussed- 


of  course,  windnw-s  arc  not  very  iist-Eul  unless  ymi  can  display  somethinij;  in  thf  m. 
At  the  end  al  llie  chiiptcr,  many  ol  iht^  tt- si  und  tiraphics  drawing  fLinttiuns  in  the 
QuickDraw  II  tool  ?;t't  v.i\\  hic  C'Ttamined,  QuiukDriiw  FI  is  responsible  for  handling 
a]|  tii.'iks  lhal  involvi^  drawing  sninfthiiig  iin  the  super  high -resolution  graphics 
icrccn-  The  Winduvv  Manager,  for  example,  mv^i  QuickDraw  li  lo  draw  window 
frames  and  speeiid  window  icnns. 

THE  SUPER  HIGH- RE  SOLUTION  GRAPHICS  SCREEN 

Belcirc  disciissiiis  the  Wiiidtnv  Manager,  it  is  netessary-  to  takf  m  close  look  at  the 
tharaLtcnsi:it;s  ol  the  super  liiph-rfscihitioii  graphics  vidt-ti  cEisplay  mode.  Once  you 
Understand  how  it  vvorki,  you  will  In;  hetter  able  tu  use  many  of  the  Window 
Manaticir  and  QuickDraw  II  functions,  especially  the  ones  that  permit  you  to  rna- 
nipulatt  (jcilnrs. 

As  shown  in  figure  6-1,  the  video  display  huiTcr  for  the  super  high -re  solution 
gruphics  mode  is  located  from  $20(X)  tn  fi9C:FF  in  hank  $E1  uf  ineninr\  .  The  area 
from  $9D00  to  $9DFF  holds  200  seanline  contrnl  hytei  and  the  area  From  SyECtO  to 
$9FFF  holds  16  color  palettes.  The  area  from  320011  Id  ■'S9FFF  in  bank  $01  shadows 
to  the  same  area  in  bank  SEl  ii  shadowing  is  cnahled.  (QuickDraw  11  does  not 
enable  shadowiny;  it  accesses  bank  SEl  video  Incatinns  directly  ) 

Two  bits  in  the  iVew-Vidcri  register  at  $E0C029  mntrol  the  characteristics  of  the 
Super  liigh-resolulion  screen  (see  figure  6-2). 

Tfi  turn  oil  the  super  hi(;h-rr.solut[ori  display  mode,  set  hit  7  of  the  New-Video 
register  to  i.  Bit  6  must  also  be  set  so  there  will  he  a  linear  relationship  between 
the  display  buQer  and  the  [Kisition  of  a  pixel  on  the  screen.  You  want  the  hnear 
relatiim.'ihip  because  screen  drawing  calculations  can  be  done  more  quicklv. 
QuickDraw  II  sets  both  hits  for  ynii  when  yoTi  call  the  QDStartup  hmction. 

When  you  leave  super  high-resoiiition  mode,  store  a  SOI  in  the  New-Video 
register.  This  ensures  that  linearization  is  off,  as  normal  lie-style  applications  expect 
this.  (It  also  permits  main/auxiliary  memor>-  .switching  just  like  on  a  lie.)  QuickDraw 
does  this  when  you  call  QDiihulDowu. 

Pi.\el  dimensions  of  the  graphiLS  screen  arc  either  320  wide  by  200  high  or  640 
by  200,  Each  line  is  defined  by  a  group  of  IfiO  consecutive  bytes  in  the  video  display 
buffer.  With  tlie  linear  mcnion'  map  enabled,  this  means  that  the  bytes  defining  a 
line  begin  at  an  offset  (frrmi  HW))  that  is  100  times  the  line  number.  The  line 
numbers  range  from  0  to  199. 

Each  pixel  in  a  line  is  assjiciated  with  eidier  four  bits  (320  mode)  or  two  hits  (640 
mode)  in  the  display  buffer.  Tliese  bits  define  the  color  of  the  pi.\el,  The  assignment 
of  pixels  to  bits  for  a  byte  in  the  display  bufiTer  is  shown  in  figure  6-3. 

When  this  scheme  is  used,  a  pixel  can  be  one  of  sixteen  colors  in  320  mode  or 
one  of  four,  colors  in  &40  mode.  As  will  be  shown  below,  the  ctilor  definitiooa  are 
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Figure  fi-I.     The  SuiJcr  Hi>;li-rej:oIiitinn  Grapliics  Display  Bllfl'er 


$A000 

t9E00 
$9D00 


Color  Palettes 
(siKteen  32-byte  tables) 

Scanline  Control  Bytes 
(f^rst  200  bLjtes) 


$2000 


Video  RAM 
( 1 50  bytes/scan  line, 
200  scan  lines) 


Bank  |E1 


NOTE:  LlKlil■<lIl^  SitXXl — StJI  l'  I'  i"  liaiilt  Stil  sliHiliiw  In  tills  hank  if  *had(iw1ng  is  ensbbd- 


sttiicil  ill  a  palette,  or  toior  table,  thiit  dL'(ii\C':  'iixteen  colors.  In  640  mode,  only 
four  of  Hit^sf  folors  are  available  to  a  0\en  pixel;  the  four  that  are  available  dcpt^nd 
on  what  uoliiiiiti  the  pixel  is  in,  iifi  incliL-atfd  in  the  fipure. 

The  pixel  width  and  color  paU'He  Ibr  a  given  huriioiital  liiif  are  oontrollpd  by  its 
.fconline  contftA  hijie  (SCB).  The  SCBs  for  the  screen  are  stored,  in  line  order,  hi  a 
2CXJ-b>  le  table  heginnins  at  $9D00  in  bonk  SET  The  format  of  an  SCB  is  shown  in 
fi^Lirte'  6—4, 

When  the  fill  mijde  bit  of  an  SCB  is  on,  color  number  0  in  the  palette  becomes 
inaLlhe.  When  a  pixel  is  assigned  u  color  number  of  0.  tht^  pixel  takes  on  the  same 
colur  as  llw  pre vinuh  iiOu-zcro  pi-vel  in  ihf  line. 


The  Super  High-resolution  Graphics  Screen  1G3 


Figure  6-2,.     Thr  Niiv-vidi'd  Register 


7 

6 

5 

4 

3 

2 

1 

0 

tE0C029 


(must  be  1 ;  enables 
bank  lalch) 


1  =  inhibit  color  in  double  high-res 
0  =  full  color  in  double  high-res 


1  =  linear  video  map  from  $2000-S9FFF  (bank  SEI) 
0  =  standard  video  map  from  I2000-$9FFF 


I  =  turn  on  super  high-resolution  screen  display 
0  =  turn  off  super  high-resolution  screen  display 


The  interrupt  bil  in  Hie  SCB  is  nonimlh'  ufl'.  Yini  may  want  to  enable  inteiru^its  so 
that  you  can  update  the  video  buffer  during;  video  retrace  operations;  this  eliiniiiales 
flickt'riiig  in  animation  sctpienw-s.  Ynii  coiild  dhu  clianj^e  tbt  eolor  pikleCteis  duriiif^ 
an  inlcrriipt  to  t'ffeetivtdy  iiitreast^  the  number  of  diflertnl  cdIois  visible  on  the 
screen . 

A  paU'lte.  or  color  tiiblr.  is  a  firoup  of  sixtieeii  words,  each  describioj^  a  particular 
color,  as  iblltiws; 


7  3  0     7  3  0 


IzeroF 

Red 

Green 

Blue 

high-order  byte         low-order  byte 


A*  you  can  see,  the  red.  green,  and  lilne  tDinpoiients  (»f  the  eolar  word  are  ejieh  4 
bits  loii^  This  means  you  can  eboiisi?  frojo  4,09fi  liifTt-rent  Lolors. 

Table  6-1  shows  the  standajd  eolor  tables  QuiekDraw  11  uses  for  each  of  the 
sixteen  I6-eolor  palettes  when  it  starts  up  in  the  640-by-200  and  the  320-by~200 
mode. 
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Pigiire  6-3.     Super  High-resolutiQii  Colur  Bits 


320  mode: 

7 

3  0 

1         1  1 

1         1  1 

1«ft  pixel 

1        1  1 

righi  pixel 

 ^  '  '  : 

color  number  {0  la  15) 
calor  number  (0  to  15) 


640  mode: 


7 

5 

3 

1 

I 
I 

1 
• 

1 

 1  

right  pixel 

(selects  from  colors  4  to  7 
in  the  palette) 

-  middle-right  pixel 
(selects  from  colors  0  to  3 

in  the  palette) 

-  middle-lert  pixel 

(selects  from  colors  12  to  15 
in  the  pelette) 

-  left  pixel 

(selects  from  colors  6  to  l  1 
in  the  palette) 
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Figur*  fi— 4.     Till'  Fdrmat  iifa  Scanline  Control  Byle 


7 

6 

5 

4 

3 

2 

1 

0 

—  (must  be  0) 


color  palette  number 
(0  to  15) 


0  = 


_  1  =  fill  mode  Is  active 
0  =  fill  mode  is  inactive 

1  =  ggnerate  interrupt  on  horizontal  retrace 
0  =  no  interrupts 

line  is  640  pixels  wide 
3ine  is  320  pixels  wide 


You  can  return  a  copy  of  this  table  Hy  pushing  a  pointtT  to  a  sixteen-word  area  and 
catling  the  QnfclcDraw  Initt^olcjrTablf  finiction. 

In  640  m(Klc,  QuicklDravv  expects  tt>i(3r  numbers  from  0  to  3  only.  In  this  situation, 
a  cfiltir  iiiiinlit  r  lii  rcaJly  an  indf.x  iiitu  llie  jiniup  ui  four  t-ulors  perniitttd  fnr  the 
pLxel  L-nliiiiin  in  ijueMtitm.  Notice  that  tlie  four  groups  of"  four  colors  in  640  mode 
are  difl'erent — Iwu  ill"  ihe  ^tuupM  use  red  and  green  as  the  secnud  and  third  cnlors 
and  two  use  blue  and  yellow.  This  means  that  when  a  horizontal  line  in  mhn-  $02 
is  drawn,  alt^niiile  preen  and  yellow  pixels  are  drawn  nil  the  screen;  they  are  sn 
close  together,  liovvever,  that  the  line  appears  to  be  one  solid  color  (lime  grtren).  An 
alternate  redygreen  line  looks  purple.  Tlie  creation  of  a  new  color  l^y  placing  difFt-renl 
colors  close  to  one  another  is  called  dithering.  By  cbanginjt;  the  64Q-Tnode  palette 
and  taking  advantage  nf  the  dithering  phenomenon,  ymi  ean  treate  many  other 
colors, 

Any  entry  in  any  palette  table  can  be  changed  at  any  time  using  QuickDraw's 
SclC^olorEntry  fiinction: 


PushWord  #0 
PushWord  #3 
PushWord  NewCalar 
_SclCo 1 orEn t ry 


Palette  number    (0   to  15; 
Color  number   (0  15) 
The  new  calar  ualLie 
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Table  6-1:    Ttie  Staiidiird  Cnlnr  Tables  Used  liy  QuickDraw 


320 -hit -2110  Mude  640-by'200  Mode 


Number 

Vuh»- 

Color 

Value 

Color 

0 

$IIIKII) 

Mack 

$0000 

black 

1 

^0777 

tliirk  wray 

$OF[K) 

red 

Z 

liriiwn 

SOUFU 

3 

S072C 

purple 

SOFFF 

wliilr 

4 

SO(X)F 

Illui! 

$0(X)U 

5 

dark  fireen 

1KX)(1F 

hlur 

6 

$(}F70 

iimnse 

$OFFO 

yellow 

7 

$t)DOO 

n-d 

$OFFF 

vvhitt= 

6 

$()FA9 

$OUO(I 

bhiek 

9 

SOFPt) 

SOF(K] 

r<'d 

10 

JOOEO 

green 

SIIOFII 

gi-L'fn 

11 

SO-IDF 

lijlllt  blur 

$f>FFF 

vvIilLc 

12 

S(>nAF 

lilac 

SOOOO 

hidLk 

13 

periwinkle  blue 

SOWJF 

blue 

14 

snccc 

light  gray 

•■SOFFO 

yellmv 

15 

SOFFF 

white 

WFF 

wliile 

If  yni]  prefer,  you  can  redefine  tlir  entire  table  at  once  by  [jaNsin^;  a  palelte  n^nnber 
4lld  a  piiinter  to  ihc  psiletlL'  dtfiiiiliuii  SetCulorTablo. 

Thore  are  alsu  yuiLkDruw  fimt'licms  Ibr  elianfliiip  ihe  standard  scaidint-  control 
bytts:  SctSCB  and  bi-f AllSC'Bs-  Vsv  St^tSCH  lo  clian^e  the  SCli  for  any  particular 
line,  in  iictAllSCUs  Ui  ussigii  tbi'  same  SCB  to  all  linen  at  cinee. 

Here  is  how  to  use  SetSCB: 

PushWoird  #188  ;Line  number 

PushWord  #182  iHew  SCB 

In  this  exanipie.  Un!'  #lSrt  bet-omes  MO  pixels  wide  and  is  associated  witJi  palette 
#2. 

Because  the  .SetAllSCBs  I'liiiLlinn  affects  all  lines,  il  requirt's  only  one  pLiranitiler, 
ihe  Tiew  SCB  valut'. 
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Figure  S-5.     The  Structure  of  a  Window 


Insert H^nu 


PushUordll 
JixHppUHpnu 

PHD 

JinHenuBar 
PLR 

JrmH^nuBar 
_InitCi;rsor 


;ni!dDl^stGl)pvlenenu 

;fldjust  iize  of  menus^nenu  birr 

:Di5pI(]y»«  Rubor 
;Tiirn  on  the  arrow  cursor 


:  Mmi  end  dispicy  thd  window: 


ihumh 


I 

i-tHii^in  (^■:>iipii  riiclii 


P' 

il 


J. 


Ill 


"iilMriiii 

rii^hl 


INTRODUCING  THE  WINDOW 

As  shown  ill  figure  6-.5,  u  standaid  uiiidow  is  made  up  of  a  rt-ctan^ilar  content 
regUm  in  wtiicli  the  window's  cniierlyiiig  d<)citniejil  is  drawii.  Surrnundiiig  the 
content  region  is  a  windcm:  framr  in  which  any  window  controls  defined  for  the 
H'iiidow  iipprar.  Methods  lor  a-ssisninf;  window  control;;  to  a  window  are  covered 
later  Id  this  chapter.  The  window  in  figiiR'  fi-,i  is  ■fiillv-lobided".  its  Iranie  euntains 
every  type  of  i-ontrol  supported  by  the  Window  Manager,  hi  prat^tice,  rnost  windows 
use  only  a  'iuhset  of  the&e  controls. 

Juht  ahtivf  die  content  region  (if  this  window  is  the  infurmatitm  har,  Most 
windows  do  nt>t  have  an  information  bar;  if  one  is  defined,  it  usuallv  contiiiii.s  a 
subtitle  Jor  the  window.  Tlie  imiin  title  appt'ars  in  a  title  har  above  the  information 
bar,  The  title  bar  aho  .serves  us  the  niediiinii^iii  for  dragging  a  window  around  the 
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screen,  To  dnip  a  uiiidfm,  iikiva-  ihc  ii^hum-  c-msnr  into  thi-  Eille  liar,  press  the 
mouse  biHton  iiiul  tlion  nunc  dn"  nnnmc  whilf  holfHiii;  the  button  tlown,  to  "drop" 
the  window  ii^to  ptucf,  reli-usi-  the  nioum'  hiitiiiii. 

Two  small  rectLingles.  the  close  ho\  i\m\  zoom  bin\  appear  at  the  left  and  rij;ht 
sides  <if  ihe  title  bar.  rfspwlivt-ly.  (V<iii  m\i\t  invhidv  a  Htlt-  b:ir  if  y{ni  wiiiit  ii  ^.'U!ie 
box  or  ii  zrnnn  hii\.\  Althoujib  ihtsc  bnxvs  an:  inside  rei:tan^;lc  dt^stribinj;  the 
title  bar.  they  art-  nnl  aitiiially  pari  itf  ihr  tttlr-  bar  itself.  The  t'lost  bos  i;^  what  u 
user  clicks  to  rcillLfv<."  a  uintlnw  trmn  thf  si'it'cii.  Thi-  aieiiii  1iu\  le-ts.  n  user  ijuiuklv 
resize  a  window:  wIkh  it  is  clicked  fur  the  fir^;!  lime  [lie  window  e>k[iiLiids  tii  Lovi^r 
the  entire  soreen  (or  whatever  si/c  is  specified  In  l]u'  pn>j;rammer);  when  it  i^s 
C'litked  rtprtiii.  i1  reliiriis  tn  its.  pr<  vi!iiis  <ivt' 

A  user  can  aisii  resize  a  windiiw  by  drajij(injt  iti  the  ^'rwir  ijnx  re^inn  of  a  windaw. 
When  it  is  drajj^ed.  iin  tiuHinc  of  thi'  rcsi/i-d  window  ^witb  tht^  top-left  turner  fixed 
ill  plac*'l  follows  lln"  mouse  iintii  the  bittlor  is  rtrletised. 

The  siri'tiU  htii's  permit  a  user  tu  \  ieiv  aii\  jiortiim  uf  a  M'indiiw  s  linderlv'ifig 
dtieiimcnf.  When  vun  click  ibc  inonse  in  j  scrull  tirnni'  iir  i\  fniiic  rl.'Jlio^l^  or  wheO 
yon  dlME  il  thuinh.  wliate^cr  is  In  dn-  window  senilis  and  a  new  piirtiiin  ill  llie 
dtKiinit'nt  beconncs  visible.  Ccmsidei'  how  llie  lifibl  ivertical)  stitill  bur  works,  Ibr 
example.  When  ynn  tlkk  ihi'  up  or  down  arrow,  the  docoTnent  scrolU  up  or  down 
by  a.  fix('d  niinil>er  oJ  piwi  hues  torrcs|)ondiiiK  lo  tme  lint  of  whitlever  iir  in  the 
diK'iimcnt,  For  a  le>t  doeinnLiit.  this  iiiiitiIilt  is  usualU  set  to  tlLt  line  :>paL'in^, 
Clicks  in  the  pajjc  rc-j^iniis  usually  Stroll  thtf  document  by  (he  entire  height  of  the 
Cmitciit  region,  nr  the  entire  lif-ii^lit  Ie'ss  one  line.  Finallv,  Von  ean  ijuiekb  brilif* 
any  portion  of  the  dficnnn'iU  into  view  by  draj^gin;;  the  SLroll  bar's  tbuiiib  up  or 
down  in  the  scroll  bar's  elevator  "ihafl:.  Bottom  (horizontal)  scroll  bars  behave  in 
similar  ways,  excrpt  that  they  cxintrol  horizontal  movement  within  the  ducument, 

The  si/i'  ot  tbc'  thumb  i  t  fteet.s  how  iiuich  □!  [be  diicunienl  iji  beinj;  shown  in  the 
L'liiitent  region.  Aj4ain,  consider  a  rifflit  scroll  bar.  The  ratio  of  tlie  height  of  the 
thumb  to  the  hc-iflbt  iif  the  SliiiII  hiir  is  the  same  ihe  ratio  of  the  height  of  the 
L'liiitent  I  e);ion  ttj  the  lu'ij;lit  of  the  doeunieut  U  the  entire  height  of  the  dotninent 
fit^i  in  the  content  reuion,  the  thumli  occupies  the  entire  scroll  bar. 

The  piisition  of  the  thumb  within  the  scroll  Imr  tells  yiiu  what  portion  of  the 
docuinciit  is  in  the  content  rcj;ion.  The  eliiser  the  tbunib  is  to  the  top  ol  a  right 
scrull  bar  (or  to  the  left  of  ti  iKiltom  scnjll  bar),  ibr  example,  the  closer  you  are  to 
the  lop  edjie  [or  left  edpei  of  the  dotumeiit,  In  effect,  the  ratio  of  the  size  of  a  page 

rei^ion  in  ii  seroll  bar  to  ihe  size  t;f  the  bar  is  the  Silule  as  the  rallH  of  the  Size  of  the 
releVikn!  oft  sereen  j'Mjrtian  of  a  unntlow  [the  portion  above  the  top,  bottom,  left,  or 
rifiht,  as  the  ca.se  may  lie)  to  the  .size  of  the  entire  window, 

The  window  behavior  jinst  desLribed  does  not  happen  automatically.  It  is  up  to 
the  proKrainmer  to  write  the  application  in  such  a  way  thai  standard  actions  occur 
wlien  window  activit}  is  detected. 
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Figure  6-G.     The  Fiirmat  i)f  tlu-  PurlSCB  B>  tc 


7 

6 

5 

4  3 

2 

1 

0 

PortSCB 


always  0 


color  palette  number 
(0  to  15) 


1  =  640x200  mode 
0  =  320x200  mode 


THE  WINDOW  RECORD 

When  yovi  first  dofilK*  ii  windim-  iwith  ihe  NewWinrlcnn'  funt-tionl,  a  window  record 
is  created  that  thr  Winilnvv  MunKjifr  uses  to  keep  track  Dl  wicidrnv  paramelfrs  One 
important  field  in  a  window  record  is  a  QuickDraw  dsnta  structure  tailed  a  GrafPort. 
A  GrafPort  ccnTiplettly  dt^scribes  a  drawing  environ  uient:  the  position  of  the  drawing; 
area,  the:  attributes  ul'  the  drawing  pen.  the  c-hai  atter  funt  to  be  used  for  drawing 
text,  the  typeface  and  c-olor,  the  background  pattern,  and  so  on, 

The  fir-it  part  (if  a  CrafPort  \i  called  the  Portlnfa -field.  II  describes  the  ijnsition 
and  sizf  of  a  reL'tanguliir  area  in  memory  within  which  an  littive  drawing  area  is 
defined.  In  mofit  cases,  this  area  will  be  inside  the  super  high-resolution  vidpo  buffer 
S!)  that  you  can  see  the  effect  ol  drawins  opt- rations. 

Portlnfu  is  a  data  atrueture  of  type  Loelnfo  and  is  made  up  of  the  fallowing  five 
fields: 

•  PortSCB  (byte) 

■  [Reservedl  (byte) 

■  PointerToPixellmagp  (long] 

•  Width  {wonl] 

■  BoundsRect  [rectangk') 

PortSCB  defines  the  color  palette  associated  with  the  CratPort  and  the  bit  size  of 
tht  pis:e?!.'i  in  the  drawing  area,  Its  meaning  is  explained  in  figure  &-fj. 

Although  you  can  associate  one  of  sistcen  color  palettes  with  each  hne  in  the 
drawing  area  (which  is  usually  the  supeir  high-resolutiun  display  buffer),  QuickDraw 
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initially  iissigns  the  same  palette  (palette  #0)  to  eacl.  line,  (The  structure  of  a  palette 
was  dcsfribed  earlier  in  this  chapter.) 

PointerToPisL-Uniilge  ctintains  the  address  oi'thc  top  left-hand  corner  of  a  rectan- 
gular dcsktup  in  whith  the  ac  tive  drawing  area  of  the  CrofPurt  is  l(:cated.  For  the 
super  hish-rewiiition  sereeii,  this  is  location  SRlSOfXX).  Width  i.s  the  nu,T.her  of 
hytes  retjuifed  to  define  a  hoc  of  pwels  extending  from  thr  let!  edge  ol  the  drawing 
area  to  tlie  rinht  edge-  it      IfiO  for  the  super  high-resolution  screen. 

Thf  precise  width  of  the  drawing  area  is  defined  hy  the  boundary-  reetangle, 
Boimddtect,  Like  anv  Quk-kDraw  reet^nple.  thi*  one  is  defined  by  fonr  integers 
representing  the  positions  ol  the  tup.  left,  bottom,  and  right  sides  of  the  rectangle. 

.Another  important  field  in  a  \%indow  recwd  is  FortHeet,  which  is  also  a  re<:tangle. 
FortBeet  describes  the  portion  nf  BoundsRecl  to  which  OalVort  drawing  operations 
will  be  confined,  [f  part  of  PortReet  lies  outside  BoundsRect,  drawing  will  be 
r^stric^ted  to  the  portion  inside  BoundsReet.  For  a  window,  this  is  the  content 
region. 

Tu  determine  the  current  value  of  ForlKecl,  use  GHPortRect: 

PustiPtr  WmdfiEct  ;PDinter    to  rectargle 

_&etPortRect  iRead  the  value  oi  PortReet 
RTS 

WipdBect   DS     3  rectangle   is   A  -.ords    (G  byte^J 

P<.rtRect  also  defines  a  local  coordimte  si/stem  for  the  GrafPort,  a  system  used  by 
all  drawing  function:,  iiffectinj;  rhc  GrafPort.  In  this  system,  the  origin  of  the 
Cian^ort— it^  top  left-hand  eon.er— has  the  coorditiates  given  hy  the  first  two  words 
of  the  PnrtReel.  These  coordinates  are  anchored  to  this  comer  and  do  not  change 
even  if  PorlRed  is  moved  from  plat'e  to  place  within  the  ar<_-:i  of  memory  described 
by  the  hijundan'  rectangle  (i  e,.  the  deslftnp). 

If  you  do  want  to  change  the  coordinates  of  the  origin,  perhaps  to  the  convenient 
(0,0)  standard  or  to  the  stroll  position  within  the  document,  use  the  SetOrigin 
function: 

PuahWord  NewK  ^ new  hnrizontal  coordinate 

PuahWortt  NewV  l^iew  i/ertical  coordirate 

_Se  t  D  r  ig  i  Ti 

SetOrigin  assign.';  the  specified  values  to  the  top  left  c-Orner  of  PortReet.  The  bottom 
right  coordinate  of  PortReet  is  adjusted  awtrdingly  to  maintain  the  size  of  PiDrtRect. 
Bonnd^Rect  is  aUo  adjusted  hy  SetOrigin  tu  keep  it  at  the  ■ianie  relative  position  ta 
PortReet, 

The  other  standard  coordinate  system,  the  [^hhai  coordimte  vtysfeni.  assigns  the 
top  left-hand  corner  of  the  total  drawing  area  given  by  BoundsRect  (usually  the 
super  high-resolution  screen)  to  the  (0.0)  coordinate-  This  is  the  coordinate  system 


The  Window  Record  111 


used  hy  a  point  in  the  Where  field  of  an  event  record,  for  t^itample,  Use  the 
Glnba,lTtjLocal  fuiictitm  to  convert  a  global  tuordinate  to  a  lot-al  toordinate: 


PuahPlr   ThePo int  ;Po inter    tog  I  aba  L  coordinate 

Oloba  1  TaLoca 1 


To  convert  in  the  opposite  direction,  from  local  to  global,  use  LocalToGIohal: 

PiiahPtr  ThePoiTil  iPointer    to   local  caor-diTiate 

Lcca  1Td61 obB I 


Use  LocalToGlobal  when  you  ha^  r  ti)  uimpare  points  expressed  in  the  local  c-oor- 
dinates  of  diffrrrnt  CnifPorts.  Cf]n\ x-rtififf  M  the  points;  to  the  same  ccxirdinate 
system  will  enahle  you  to  make  nieaninptul  totn  pari  sons. 

The  tonceptuaJ  drtiwillg  spat'e  fbr  Ou'^'^l^i'i*^'  operations  is  a  square  Rrid  that  is 
32K  pixels  wide  and  32K  pixels  hij^li,  Tlie  rairdinate  orisin  Is  in  the  eenter,  so  the 
coordinate  limits  lor  the  horixontal  and  \trttfiil  axL-s  ranf^e  from  -16K  tci  +ieK.  If 
you  tr\'  to  draw  outside  this  range,  the  systen:  vvill  behave  impredietiLbly. 

Kpfp  in  mind  that  even  when  tou  draw  iu'iide  the  Jibsolutc  hiiundaries  only  the 
bits  for  pixels  tallins  within  the  tuntent  region  of  the  window  (and  not  obscured  hy 
other  windows)  wil!  he  transferred  to  the  memory  area  assnciated  with  the  content 
reg^ion. 


WINDOW  MANAGER  START-UP  AND  Sllt'T-DOWN  OPERATIONS 

Because  the  Window  Manager  functions  use  QuickDraw  11  functions  to  perform 
screen -drawing  operations,  you  must  initialize  QniekDraw  before  initializing  the 
Window  Manager.  To  do  this,  u^e  the  Ibllowing  calling  sequence: 

PuahWord  DPftddr  jflddreas  of  3-piage  area  in  bank  *D0 

PuahWord  #(80  i*aO   =  B^0ic200    /   «00  =  330x200 

PushWord  #Q  ^MaxUidth   [0  =   screen  wldtti) 

Pu5tiUorid  UflerlD  ilD  rcturTicd  by  ritl^tartup 

_flDStflrtup 

DPAddr  is  the  two-byte  address  of  a  three-page  area  in  bank  $W  that  Qi^'ckDraw 
uses  for  direct  page  space,  This  space  can  be  allocated  with  the  Memory  Manager. 
The  second  parMieter  pushed,  MasterSCB,  is  the  seanhoe  control  byte  QuickDraw 
will  use  for  each  of  the  2<»0  lines  on  the  screen.  It  is  nonnally  S80  lor  540-by-200 
mode  or  ^OO  for  320-by-20O  mode.  The  next  word  pushed  is  MajiWidlh.  the  width 
tin  bytes)  of  the  larppst  pixel  area  in  whith  QuickDraw  will  be  asked  to  draw;  a 
value  oft)  sets  MaxWidth  to  the  screen  width  (160  bytes).  The  last  parameter  is.  the 
program  ID  that  was  returned  by  MMStartup, 

To  initialize  the  Window  Manager  itself,  use  WindStartup: 
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Pu5hUord  U^er ID 
_WiTidStarlup 


;1D  retuTTiEd  by  nriSlartup 


WiruIStiirtup  s  onlv  parainc-ter,  UserJD,  is  the  ID  tmmher  relumed  by  MMStartup. 

WindSlarUip  cli  ^rs  ihr  Window  Maiihgn  's  iiittTnal  lisl  of  wiiukw  s  and  defines 
the  entire  siiiUM-  hinli-rfM(lulioil  ^(.roi-n  ll^  tlif  Wiiiclmv  MiiiiJiierV  dfsktup.  ll  di^es 
not  draw  the  dcslrtup  tlself;  for  that  use  Rffrt-shlJcsktop; 

PushLong  #0  ;0   ^  entire  %crsen 

Ref  r  eshDes  k  top 

Befresli Desktop  uses  a  dtliudt  hackuroiind  paltcm  and  colnr  lu  draw  the  di-sktop. 

When  you  are  ^11  through  with  llie  Windinv  Manlike'''  ^"'^^  i-"*  P">Kr;iin. 

call  tlie  WindSliutDnwii  functiiiii  lo  rt-least-  ihe  data  struftiires  and  meiiiory  areas 
it  uses,  WindSliutDowiL  require*  no  parameters. 


CREATING  A  WINDOW 

To  create  a  new  wiriduw,  u^e  NewWindow.  Tt  builds  a  v.-indnw  rcLwd  deta  structure 
fmm  a  speeificd  iiarLullot<T  list  and  adds  the  record  to  an  liitL-rnal  list  of  window 
retnrds  maintiiined  bv  the  W  indow  Manager,  U  may  or  may  not  display  the  window 
on  the  sereen.  depending  on  Inm  you  initialk  define  the  WFrame  parameter  [see 
helow  ).  If  you  dt^fine  it  as  invisible,  you  can  display  it  hy  passine  llie  wiiiduw  pninter 
to  the  show  Window  function. 

NcwWindow  requires  only  one  parameter,  a  pointer  to  a  parameter  hsl  dc«ribinp 
thf  properties  uf  the  window,  It  returns  a  pointer  tu  iht^  window  retord  tor  [>  if 
space  for  the  wuidow  record  could  not  be  allocated).  Here  is  how  to  use  New^ 
Window: 

jSpflce   for    result  (long) 
iPointer  parameter  list 

;SBve  window  pointer 


PuahP Ir  Wi ndParma 
_HewWindou 
PopLong  WindowPtr 


\ewWindow  Paramtlers 

The  parameter  lisl  fpferred  m  in  the  eall  to  Nc-wAVindow  contains  nineteen  param- 
pten^  tliat  describe  the  appeaniTiee  of  the  windaw.  Some  paranitters  are  only  tor  the 
use  ul'  the  TaskMii^ter  iuncfion,  which  retrieves  events  and  handles  mouse-down 
aelivily  in  a  window.  The  snbruutine  in  listing  B-1  shows  how  to  define  the  window 
shown  in  fipure  6-5. 

A  description  ot  eacli  of  the  parameters,  in  order  of  appearance  in  the  parameter 

list,  follows; 
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Figure  6-7.    Tht^  \Vind"w  Frame  Bit  Vector  (wFrame)  Used  by  NewWindow 


I5MI3I211I09   8    7    6    5    4    3    2  10 


F_Title 

F_ClQse 

F_Alert 

F_Rscrl 

F_BScrl 

F_Grow 

F_FlEX 

F_2oonn 


^ —  F_Hiltted 

 F„ZQomed 

 F_AIlocQted 

 F^Ctrl^Tie 

 F_lnro 

 F_Vis 

  F_QContent 


paramtenglix  {word).    This  h  the  number  of  bytes  in  llie  window  parameter  table. 

tcPrame  (word).  This  is  a  IjiI  vcrctur  deseribinff  the  appearance  nf  the  window 
Branie  (see  figure  6-7).  It  U-ts  ynu  Lxeatt^  \viiidous  with  cir  without  the  fullowiiig 
window  foiitrols  in  th<'  frjimn] 

•  Title  bar 

•  Closf  bi!\ 

■  ZfHUll 

•  Hijilit  j^cTiill  bar 

•  iiotloiii  sLTull  biir 

•  driix*'  ha\ 

•  InfnriTiiitiijn  bin 

You  can  also  use  it  to  indicate  whether  the  window  is  movable  (can  be  dra^^ged 
ariiiifid  ibe  screen!,  at  its  zinjined  size,  or  visible.  Additictiial  bits  refieet  wbi^ther 
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the  window  was  created  by  NewWindow,  whether  tlie  c-oiitrols  arc  tied  to  the 
window,  and  whcthc'r  a  uiuuse  dick  that  activates  a  window  is  to  he  returned  tu  tlie 
d]ipliLdtiiin. 

With  two  exceptions,  eiieh  control  is  independent  of  any  othrr  The  first  tvyteplion 
U  the  grow  bax — il' its  bit  is  set,  the  rijjht  sltoII  bar  or  bottom  stroll  bar  bit  must 
alsL)  he  iet,  The  second  exfcptiDii  rt'kteh  to  the  title  bar — if  the  cIonl-  hux  or  zouin 
box  bits  are  set.  the  title  bar  bit  must  be  set  as  well.  Althini^;h  it  is  not  recjuircd.  if 
you  define  a  windi>w  with  a  zuuni  ho\,  yon  should  alstj  define  a  f^row  boK  so  that 
the  window  can  be  iniide  any  coiueiiient  S!?-r. 

A  common  window  fr;iinJ  value  is  %1  inil  1 1 1 1 1 1()!)I01  (SDFE5).  Thus  defines  a 
visible  window  that  h^s  a  title  bar,  close  bo\.  ?;croll  harn,  graw  Imx.  and  a  y.onni  box. 
The  window     u,k(>  dray^;ahle. 

Here  is  the  meaning  iif  each  bit  in  the  window  frame  bit  vector; 

bit  0  1  =  Window  is  highlighted  (active) 

F_H3LITED  0  =  Winduw  is  tnihipt!lif;hted  (inactive) 

This  hit  is  used  by  the  Window  MaiiaRer  uJter  the  window  is 
defined;  it>!  value  is  ignored  by  NewWindow. 

bit  1  I  =  Wiudow  is  zonmed  out 

F_ZOOMED  0  =  Window  is  zoomed  in 

If  the  window  is  roomed  out.  it  will  zo^m  in  wlieji  the  zoom 
box  is  clicked  next.  If  it  is  zoomed  in.  it  will  viumi  out. 

1  =  Window  record  was  .illtKated  by  NewWindow 

0  —  Window  record  Wiis  allocated  by  the  application 
If  this  hit  is  set  (tlie  usual  casf).  the  window  record  is  autn- 
niaticiihy  disposed  of  when  CloseWiiidow  is  called. 

1  =  Cimtr»Is  ill  tlie  window  arp  not  tied  to  the  active/inactive 
slate  of  the  window 

(i  —  Contnils  are  tied  to  the  state  of  the  window 
The  usual  viiluc  fur  this  bit  is  0.  Tliis  causes  tlie  scroll  controls 
to  be  dimmed  vvheii  the  window  is-  deaetivated 

1  —  The  M-iiidow  hai  an  infonnatinn  bar 

0  =  The  window  diKfS  not  liave  an  information  bar 
If  this  hit  is  sft.  the  wliifoDcfProc  field  of  the  ^^'illdow  rett>rd 
must  point  to  an  infonriatiOTi  bar  drawing  procfdnre.  The  field 
must  not  hp  zero. 

1  —  The  window  is  visihle 
0  =  The  window  is  invisiltle 

If  this  bit  is  0,  l:he  wijidow  will  not  appear  nn  the  screen  after 
NewWindow  iji  called.  Use  ShowWindow  to  make  the  window 
visible. 


hit  2 

F  ALLOCATED 


bits 

F  CTRL  TIE 


hit  4 
F  INFO 


bits 
F,VIS 
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hit  15 
F_TITLE 


1  =  The  vvindim  has  a  title  bar 

0  -  Thf  wiiidoiA/  does  not  have  d.  title  bar 


uiTitle  (long).  This  is  a  pointer  tn  the  title  of  the  window.  Tht  lille  is  a  string  of 
ASCll-enmdcd  characters  preceded  by  a  Icnptli  byte,  To  isolate  tb^  title  from  die 
background  palt<^^rn  of  the  fille  bar  iiK-lude  -a  space  L-barseter  at  rhe  beKiiinins  and 
end  of  the  title  strijig, 

wBe/Con  (lonR).  This  is  3  rrb-reiicc  constant  dffi]ied  by  the  appliLation.  It  is  not 
used  bv  anv  Whidnw  MaiiUSrr  lunctions.  H  rati  hold  anything  you  like,  such  as  i 
pointer  or  handle  to  a  data  area  you  would  like  to  associate  with  the  window. 

uiZoom  (rectangle}.  Tbis  r*?itan^;le  describes  the  size  of  tW  content  r<ision  when 
the  window  is  ziiinned  bv  eliLking  in  its  znom  box,  Like  those  of  any  reclaiisle,  this 
rectanjiii  's  Liwrdiniites  are  in  top.  lefl,  bothnn,  right  (TLBR)  order.  If  you  specily  a 
zoom  reLtaiigk-  c^l  (U.O.U.O].  a  default  rectangle  that  describes  llic  entire  streeii 
(except  the  menu  bar)  is  used. 

tvColor  {long).  This  is  a  puinter  tn  the  window  frames  color  table.  If  tbis  painter 
is  zero,  a  delimit  cnlor  table  is  used. 

tcOrigin  (poin*).  This  is  the  piKiiiou  in  the  window's  underlying  dof  ument  thai 
corresponds  to  tbe  lop  Itll-hand  corner  of  the  content  region.  This  value  is  used  to 
compute  the  positions  of  the  thumbs  in  the  riRht  and  botti}m  iLroll  liars,  TaskMaster 
updates  tbis  valoe  in  the  window  returd  when  a  strolling  operation  oeeurs 
Ta.skMasler  also  uses  SelOrigin  to  move  the  origin  of  the  coiiteiil  region  to  tbis 
point  before  callin)i  the  routine  to  update  the  uindo^v  (!!ee  below);  the  origin  is  reset 
to  (0.0)  on  return  from  the  update  routine.  If  you  draw  inside  a  window  outside  of 
the  update  subroutine,  first  call  StartDriiwing  to  adjust  the  origin  properly,  use 
SetOrigin  to  return  the  oTigin  to  (0,0)  after  ditiwuR. 

u'Daia  {long).  Tbis  is  the  height  dow  word)  and  width  (hiph  word)  of  the  entire 
document,  mea-sured  in  pixels.  This  data  is  needed  to  draw  the  ri^ht  and  bottom 
scroll  bars  properly.  Set  tbe  height  or  width  to  0  if  yoo  are  not  using  right  or  bottom 
scroll  controls,  respectively. 

Ei'Muj  (long).  Tbi^  is  the  masimum  allowable  height  (l.)w  wordl  and  width  (high 
word)  of  the  oonti;nl  region  when  resizinji  the  window,  TaskMaster  passes  this  valoe 
to  GrowWindow  when  a  numse-down  event  occurs  in  tbe  window's  erow  box.  Set 
it  to  0  if  yitu  wunt  lo  use  tbe  default  value,  which  the  height  and  width  of  tbe 
desktop, 
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wScroll  (long),  This  is  the  number  of  piAtls  ttj  hLTtt]!  the  cuntent  rt'fiiDii  when  the 
lip  nr  dow.h  nrrow  hs  the  right  SltoII  bar  is  •ieleLted  (hlw  word)  and  the  nLiiiiI)t=r  of 
pixels  lo  scroll  when  llie  left  tir  rif;ht  arrow  in  the  huttotii  sercill  Unr  is  ?,!"leetc'd  (liijjh 
word).  These  values  are  csed  by  T;isltMa.stt'r  tu  handle  activity  in  a  h;LT(ill  lia.r. 

icPage  (long)  Thii^  is  the  niinil>f-r  nf  pixels  ta  semll  ihc  t-ontenl  repiun  when  the 
up  (ir  down  pjfie  rt?t;ioii  in  the  right  scroll  biir  is  splceted  (low  word!  and  the  lUhtiber 
of  pixels  to  scnill  wh'Pn  iht-  Icfl  or  rinht  pisge  resioii  in  i\w  hottuni  stmit  linr  is 
seleetcJ  [high  ward).  These  values  are  ust'd  by  TiiskMastcr  to  hitikdie  activity  in  a 
scrol]  bur. 

wlnfoHefCon  (lun^).  This  the  referenee  cunstiint  pa.s>ied  to  tlie  information  bar 
draw  routine.  This  constant  Ciin  be  anything  the  applieatinn  hkes.  It  often  holds  a. 
pointer  tu  n  line  ul  texl  tu  lie  drawn  in  the  jiiForm^tinn  har- 

wlnfoHeight  [wordj.     This  is  the  heisht  til  the  inlbrniatiun  bar. 

wt'rameDeJFroc  {Innji;).  This  is  a.  pointci'  tt>  tin*  window's  definition  procedure, 
Set  this  tu  0  for  n  standiird  dueunient  window, 

iflnfoDefProc  Uoug)..  This  is  the  addrej>!i  of  tKe  routine  TaikMister  ealls  tu  draw 
the  eofiteiit.s  ol  the  inlurmiUioii  bur,  Siieh  a  routine  must  be  iiiiitahed  if  the  wP'rame 
byte  indicates  tll^l  the  v^  IirIuw  !uis  Lin  iiiionnatiun  liar;  if  Lhi^  reutine  i^  not  installed, 
the  system  will  crash  when  the  window  is  drawn.  Thie  Window  Manager  pushes 
thrcf!  parameters  on  the  .stAck  before  tailing  ihe  inFonnation  bar  5ubriiotiiie  with  a 
JSI,  instriittion:  a  pointer  lo  thr  enclosing  rettangle  tor  the  inforniatinn  bar,  the 
wlnfoRpfC'on  vahie,  and  a  pointer  to  the  window.  These  parameters  must  be  re- 
moved from  the  stack  before  the  siibrnutine  ends  with  an  RTL  in^tructiun.  Note 
that  h('tor(>  the  routine  tries  to  itctoss  the  ijpplicalion's  tlireet  pape  or  duLi  spaee.  it 
should  fic't  the  direct  papp  and  data  bank  registers  accordingly  (after  saving  the  ones 
passed  to  the  rciutinc  J.  On  r.xit.  the  initiiil  vulnes  for  these  reRis!*TS  must  be  restored. 

wContDeJP^roc  Oong).  This  is  thr  addre'is  nf  the  routine  TaskMaster  calls  to  draw 
the  windawM  etrntent  region  in  rcspimsp  tn  an  update  event.  Before  TaskMastcr 
calls  the  routine,  it  sets  the  local  cnordniates  of  the  top  left  i:x>rner  of  thf  content 
region  to  the  positions  indieiited  by  the  values  oi  the  scroll  controls  (if  appliealile) 
and  calls  BegioUptiate.  On  entry,  the  direet  page  and  data  liank  rcgisteris  may  not 
he  the  same  as  when  TaskMaster  was  called,  su  thf  routine  will  have  to  ehanj^e 
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ihcm  til  iifcvsh  tkf  Lipplitiilinii's  iMvect  page  and  data  areus.  The  ruiiiint"  must  end 
Willi  ail  RTL  iiislrijiL-timi  If  x-.-CnriH^t'lVniL  is  0,  tn  it' TjskMtihtt  r  is  no!  ir>.i'd.  Hie 
applk-^liini  itsfh  iiiiisl  trap  iipdatt'  i-vents  mid  liaiidk-  llifiii  in  -^ii  iippropriaU'  wiiy. 

a-Position  (riuttansle^,  TliiH  rrctaiiflle.  jjivtli  in  slohiil  cnordinates,  describes  the 
ini("ial  position  and  sm:  ol  tlir  windim-  ^  Lciiili'lit  rc■^^i^l■(l. 

trPiane  [long).  This  is  ;i  i^niiitiT  tci  ihf  window  ht-hiiid  whitli  this  window  is  to 
iipiiciir  (liinj;!,  1(  tht-  paiiilcr  is  -1,  ihe  window  iippt-iirs  mi  top.  il  (i.  the.  window 
itppravs  at  llic  biittoiii. 

leSttfraf^e  iUmg).  This  is  thr  addn-ss  (li  tlic  iiunnon'  aren  \u  use  for  thu"  wintlow 
retni  d  \\uni!.\.  St-t  it  to  0  il'  N cwWiiidovv  ir.  In  allocate  tht  iiieiiiory  -ipacc  fi»r  yusi  hy 
callinji  NL'wHiLTidtt?  itlu  usniil  eysel, 

THE  I>FORMATION  BAR  PRDCKDURE 

Tlu-  jli-nend  slriietlire  nf  ;in  intnriiiatiiiii  liar  pnxcdiire  is  shown  it!  Ii^ti^Jt;  6-2.  In 
thi^  partiLuliir  exainplo,  a  !ino  iil  tftf  ih  cenU-rrd  and  drawn  in  llie  inli)irmation  bar. 
A  pninttT  to  the  text  striiiw  i.h  in  [lie  w  liitbRcirinii  parameter 

UPDATING  A  WINDOW 

The  wGuntDefVnX-  (Lipdatt'}  siibiimlirK-  reh-rTcd  tu  in  llie  NtuW'inilow  parameter 
liit  in  imiiortaiil  beciuisc  it  is  respmisihle  for  fnsurinti  that  newly  cspost'd  portions 
of  a  wintlinv  are  pnipi  rly  fi]lt  d  m.  W  ilhniit  mjl-H  a  liiibrtmtiiio,  porrion.^  of  llie 
windiiw  will  be  ersiM-d  when  oilier  v^  indows  are  nmved  Irom  ill  iVont  uf  it  or  wlien 
the  window  is  enhir^rd.  The  TextHemdrr  program  shown  laler  in  this  ehapter  is  an 
fxaiaple  of  how  to  write  milIi  a  MibrnutiiH"  for  a  window  i.i>iitainin^  linei  o±  lf\t. 

If  wComDeiPi'Of  is  [',  update  ewiits  uit  passed  through  tu  the  appliL-ation  for 
handling;,  [Vou  shanld  elc^r  wContDen^riic  when  dt  siffning  New  Desli  Att-essories 
beeause  um  eannnl  hi-  sore  tlial  TaskMiwler  heini:  used  by  thr  in:nn  Lipplifiition; 
see  fhaptt-r  9,1  Tlie  npdate  handler  is  similar  to  a  wCoiitOefProc  subroutine  hot 
musl  iiiclnde  some  extra  window'  maiiagt-ment  chores.  To  handle  updates,  first  call 
Begin  L'pdiitc: 

PustiLorg  WindowPlr  jPoirter   to  wiTidow 

_Beg  1  TiUpd^  t  e 

BeginUpdiit^?  sav<?s  the  window's  current  visdile  region  ^which  deiienbes  tlie  pnrtitm 
of  the  window's  eonteul  r^'gion  you  olui  aetii^lly  sor  on  the  wTeen),  sets  the  new 
visihk'  reiiiim  to  the  iTilersetlicm  of  tlie  old  visible  reunion  and  ihe  update  region, 
and  then  empties  llie  update  region. 
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AFtf-r  fallfnj;  Hfi;mLJpilatt\  pass  the  vvindnw  piiintcr  tu  SlartDrawirig  to  scfect 
the  window  ftir  drawing  activity  ami  lo  uliKn  tl^'"  "m^lin  ot  Ihe  LOuLeiit  region  tn  the 
position  rt^flccted  hy  t!ie  values  of  the  ihtmibs  in  the  Seroll  eontrols.  This  aUgns  the 
active  pnrtKin  nf  the  dneuinent  wUh  tile  window's  cnnff'nl:  rfj;ioii.  Tlien  redrau'  thf 
portiMn  uf  tlie  wiiiduw\  dtH.iirii(fiit  lliat  appears  within  thf  new  visible  region.  To 
do  this,  it  is  actually  tfasier  tu  redraw  ihe  entire  content  region  of  the  window, 
bc'e:ui«'  dfiinK  so  avoids  the  problem  of  dctct  mininp  how  to  draw  jnst  an  iirhitrary 
portuHi  of  it.  To  dn  this,  of  {.curse,  you  must  aKvaVn  keep  a  record  of  fsactly  what 
is  in  tlie  windnw,  This  can  be  (he  most  dilTitult  part  of  developing  an  application. 

After  the  screen  hai  been  redrawn,  call  EndUpdate  to  restore  the  original  visible 
region: 

PushLoig   LJlTidowPtr  ^Pointer    to  window 

_EndlJpda  te 

Next,  set  the  orisio  of  the  window  hack  to  [0,0f  with  SetOrigin; 

PlishWord  #0 
PushWord  #D 
_Setflr ig 1 n 

Thi'  \Vmd^J^^  Manager  does  not  work  properly  if  you  do  not  return  the  origin  tu 
(0,0)  alter  updating  die  window, 

CHANCING  TtlE  PROPERTIES  OF  A  WINDOW 

After  vou  have  t  reated  a  window  with  NewVVindow,  you  will  need  tci  change  some, 
of  that  window's  properties  in  certain  situations.  For  instance,  you  should  alter  the 
DataSize  parameter  to  reflect  a  change  in  the  size  of  the  window's  underlying 
doeumeiit  Su  dial  the  scroll  contrnl.';  can  he  redrawn  m  proper  proportion,  Tu  change 
hucU  properties,  you  must  update  field?;  in  the  window  record  created  trom  tlie 
N'ewWiiidow's  paraoiet'Pr  list,  not  in  the  parameter  list  itself,  You  do  this  with  a 
group  of  Set  functions,  one  for  each  of  the  named  fields  in  the  parameter  list. 

Table  6-2  cniitains  a  list  nf  the  relevant  Set  lunction.s.  When  you  change  a 
parameter,  the  appearance  nf  a  window  may  not  immediately  chaage  to  reflect  the 
value  uf  the  new  pariimctcr.  Tn  force  the  window  to  he  redrawn,  fir_st  hide  the 
window  and  then  make  it  visible  a^gain; 

PushLoTig  UliTidowPlr 

_Hi-deUirdow  iRemovE  window  from  acreer 

PuahLoTig  Uindo^Ptr 

_Shai''Wj  ndonF  '.tlake  the  window  viaiblr 
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Tatle  6-2;     Fimttioiis  fur  Sfttm^^  Window  P^ira meters 


Function  

SetWFrame 
SeiWTitle 

SetFi.illHeL't 
SetFrameColur 
SetConten  tOri  gi  n 

SetDataSize 

SetMaxGrow 

SetScroll 

SetPage 

SetlnfoRefCon 
SelDeiProc 
SetlnfoDraw 
SetCorttentDraw 


Description  

Sets  the  window  frame  bit  vector 

Sets  the  title  for  the  window 

Sets  the  reference  constant  for  the  window 

Sets  the  zoom  rectangle  for  the  window 

Seti  the  color  tahle  to  be  used  with  the  window 

Sets  the  horizontal  mid  vertiLal  offsets  to  the 
data  area  eiiriesponding  to  the  top  left-hand 
forner  of  the  window 

Sets  the  width  and  heii^ht  of  the  data  area  for  a 
window 

Sets  the  masimoiii  width  and  height  for  a 
window  that  can  be  resized 

Sets  the  inimhfT  of  pixels  to  bLToll  one  hne 
horizontally  ind  the  number  of  pixels  to  scroll 
line  line  vertieidly 

Sets  the  number  of  pixels  to  scroll  one  page 
horizontally  and  the  number  of  pixcK  to  stroll 
one  page  vertically 

Sets  the  parameter  passed  to  the  information 
bar  drawing  protedore 

Sets  the  address  of  the  window  definition 
proeedure. 

Sets  the  address  of  the  infttrmatioti  bar  drawing 
pHK-edii  re 

Sets  the  address  of  the  wiadow's  opdate 
procedure 


If  there  is  joore  than  one  window  on  the  screen,  eall  SelectWindow  after  the  code 
seciuenL*  above  to  make  this  wintlow  the  actn  c  one. 

There  are  also  Gel  functions  corresponding  to  each  Set  function,  L'se  them  to 
determine  the  current  values  of  the  window  parameters,  With  some  exceptions. 
Get  functions  are  all  called  in  the  same  general  way; 
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1 ,  Push  space  for  result  [word  nr  ]ong) 

2,  Push  a  pointer  to  the  window  record  {long) 

3.  Cal]  the  Get  fiinctioii 

4.  Fop  the  result  (the  window  paraineter) 

For  a  funutLDti  dealing  with  strings,  the  result  is  a  pointer  to  the  string. 

Thf  exceptions  rrktc  to  those  functions  dealing  with  rectangles,  strings,  and 
other  data  structures  kjny;cr  than  four  byles.  Insteail  of  pushing  spaoL-  for  a  result, 
push  a  painter  to  a  space  for  the  rectangle  or  stnTig.  The  fui^ction  returns  the  result 
in  this  spatie,  so  yoi]  do  not  have  to  pop  a  result  from  tlie  stack. 

REMOVING  A  WINDOW  FROM  THE  DESKTOP 

When  you  are  finished  with  a  window  for  goud,  use  CloseWindow  to  free  up  the 
space  reserved  for  it  [if  it  was  ereatrd  with  MewWindow),  rennive  it  from  the  window 
list,  and  erase  it  from  the  screen: 

PushLcng  Uli  ndoMiP  t  r  ;PoiTiter   to  wlrdow 

_Cl05el*jLridcw 

CloseWindow  causes  the  window  in  the  plane  just  helow  the  window  that  was  closed 
(if  any)  to  be  highlighted.  It  also  generates  an  activate  event  for  thi.s  window.  Once 
a  window  is  closed,  you  cannot  use  it  again  unless  you  redefine  it  with  NewWindow. 

If"  you  simply  waTit  to  erase  a  window  fr[jm  the  a4;reen  without  destroying  its 
rec-ord.  use  HideWindow  to  make  it  invisible: 

PushLong  WindowPtr  ;Pointer    la  window 

_H  ideW  L  ndow 

To  make  the  window  visihle  asaiu.  pass  its  pointer  to  the  ShowWiudnw  function. 
You  will  also  use  ShowWindciw  to  display  a  window  for  the  first  time  il  the  visible 
hit  in  the  window  frame  wort!  is  0  when  you  call  NewWindow, 

Be  aware  that  calling  ShowWindow  will  not  make  the  window  active  if  there  are 
other  windows  already  cin  the  screen.  Use  SeleetWindaw  for  that; 

PiishLong   WindouiPtr  iPolnter    to  window 

_Se  le-c  t  Window  ;acljuate  ttie  window 

SelectWindow  removes  the  hijfhlishtiug  from  the  previously  active  vrindow,  brings 
the  specified  window  to  the  front  of  the  screen  and  hiplilights  it,  and  then  generates 
the  appropriate  activate  events, 

You  will  use  SeieetWindow  more  often  tn  activate  an  inactive,  but  visible,  window 
when  Gi?tN  est  Event  returns  a  mouse-down  event  that  FindWindow  iays  took  place 
inside  an  inactive  window.  If  you  are  using  a  TaskMastcr — rather  than  a  Get- 


1S2    Windows  and  Graphics 


NextEvent — event  loop,  you  will  nnt  atJtually  ha^  t  tu  Lall  Select  Window,  because 
TaskMaster  calls  it  for  you- 

To  deteniiiiie  il  the  windnw  in  whicli  an  {-vt-nt  tuok  plat-t^  is  ihe  active  [friintiiiubtj 
w.'iiidow,  use  FronlVViiidcnv: 

PHA  1 5pace  for  result 

PHA 

^FronlWi  ndow 

PopLorig     CurrentWindo'W     ;Pap  the  ><jiridow  pointer 

If  tlie  result.  Current  Window,  inatclies  the  value  i>f  the  window  pointer  th&t 
Fin dWi ndow  retunis,  the  atlivily  did  take  place  in  the  activt  window. 

HANDLING  MOUSE-DOWN  ACTIMTV  I,\  WINDOWS 

The  user-interface  guidelines  define  the  actions  that  should  take  place  when  viiriijus 
parts  of  a  window  arc  clicked,  Fur  oainplc,  a  dick  in  an  iiiattivc  windt»w  should 
ectivatc  the  wiiidow  and  hrin^;  it  tu  the  front  of  die  stfeeti.  The  Windnw  \f Lin:iger'ji 
TiiskMiister  TunL  tion  (intrnduued  in  chapter  5)  ped'ortns  many  of  the  standard  at  tions 
for  you,  so  use  it  unless  you  need  to  deal  with  a  niiiuse-down  event  in  a  different 
way.  This  section  dcscrihes  exactly  how  TbiakM  aster  reiu  ts  to  various  events  iO  (hat 
if  you  want  to  handle  them  on  your  own,  yoit  will  know  roughly  what  to  do. 

Here  is  a  sulirouline  you  Lx^uld  call  to  get  a  TaskMastcr  event  to  work  with-  the 
subroutine  returnri  an  event  cude  in  the  accunudiltor: 


EvertLoop 

PHft 

iSp^ce    for  resLiit 

Pii5hWord 

1  #SFFFF 

; 1 i  Dw  all  events 

Pii5hiPlr 

Ta5  k  Record 

iPoirter   to   task  record 

_Ta5k  Ma  s  t er 

iOel  fvsni  cade 

BEQ.  EvertLaop 

;LDap  if  null  e^/eIll 

RTS 

ftNOP 

wha  t 

DS 

message 

WtlBTI 

DS 

<) 

wliET  e 

DS 

1 

mad  1 f  ier  s 

DS 

2 

TaakDatB 

D5 

4 

Tb9  kMfli     r  data 

Tb9  k  Ma  5 1 

DC 

M'tOOOOIFFF'    sTflBtMflBler  handles 

When  Ta.skMastcr  detects  a  muuse-dowii  event,  it  calls  the  FindWindiuw  function 
to  determine  in  which  part  of  a  window  the  event  occurred.  The  lucation  codes 
FindWindow  can  rettini  are  shown  in  tabic  fi-^l^- 

If  FindWindow  returuh  li  StKWU  event  code  (wNoHit),  the  event  shouSd  be 
ignored. 
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Table  6-3:     Lr«:-atioii  Codes  RetLimecI  by  FindWindow 


Syrttbolic 
Name 

Coda 

Memiing 

wNiiHit 

mm 

Not  in  A  window  at  all 

win  Desk 

$0010 

In  llie  desktop 

wliiMemi  Bar 

$0G1I 

111  ihe  system  iiLemi  liar 

wlnCnntent 

S0Q13 

In  die  window  s  t'oiitent  region 

win  Drag 

80014 

In  the  window's  drag  region 

wIuGrnw 

$0015 

In  the  window's  size  bq* 

wlnCJoAwav 

$0(1  Ifi 

In  tht'  window's  close  box 

S0017 

In  (he  window's  zoom  box 

winlnfd 

$0018 

In  the  window's  infortnation  bar 

win  Special 

$0019 

Special  menu  item  selected  (*) 

win  Desk  Item 

$001A 

Desk  accessor}'  item  selected  (*, 

wlnFrame 

SQOIB 

In  any  Other  part  of  the  wnndow 

winSysWindow 

%Hxxx 

In  desk  actessory  window 

MITK.  In  the  iTistiiTiL(.:i  nwrlsi!!  Iiv  an  Mlcvisk.  FhidWindow  mil  H[  CtJiilly  retvim  llif-si-  tode*.  they 

ari'  r-^liiriie'd  by  TiiskMii-.k-t  it  TaikMiialir  Is  nul  (.tMiFipjrt'd  lu  ik-A  viiU  tli-sk  .iturss-iriirs  seleErtion^ 
[wtnDeskltem!  ur  if  standard  n]itin|</du<>inK  nieim  items  are  usud  !«■  In  Special). 


Note  that  if  ihe  liiKh-urdt-ir  bit  of  the  lot  atinn  Lode  is  set  to  1  (that  is.  tht-  code  is  of 
the  fiiriii  ^8\>;xl,  the  evL-nl  OCflincd  in  a  de^ik  at.™ssor>'.  TaskMiSStcr  simply  passes 
the  e\tnl  to  the  at  Lt-ssorv  by  calbn^  Sy.sttni Click,  It  then  exits  and  returns  a  null 
event  so  thai  the  applk-atioiii  will  iiat  tiy  tt>  hiiiidlc  ihc  event- 
Other  rcFiuh  codes  refer  to  appllLatiim  wiiid"w_s  and  are  handled  in  difl'erent  ways 
by  TaskMastcr.  These  tndes  are  described  U-low, 

ll^ln^feHttB^^r.  TaskMa^ter  handles  activity  in  the  menu  bar  by  caJliiiH  MejiuSeWt 
to  dL-teniiiiie  which  menu  ilem  was  selcLled,  See  chapter  7  for  more  inforniatinn 
on  how  TaskMa^ter  heliavcs  bpyiind  this  staEc.  Afttr  processinp,  TaskMastcr  exits 
and  return^j  a  nnll  eveiil  code,  wIiiMeiiuBar,  wIiiDeskllcm,  m  wlnSpt^cial. 

talnContent.  If  llie  wiridtm'  is  nut  active.  TiLskMasler  calls  Select  Window  to  mske 
it  active,  exits^  and  reliinis  a  mill  event  citde,  II  it  is  active,  TaskMasttT  jiuts  a 
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pointer  to  the  windnw  in  TaskDi^lii,  exits,  and  returns  tht-  wlnContent  ct>de.  It  Is 
then  up  hi  the  iipplic-atitui  tu  handle  the  eviynt  in  apiirnpritite  way.  by  repositioning 
a  cursor  in  n  lint-  of  ti-xt  nr  hij^htiptiting  nu  icon,  fur  example,  II  the  interior  ot  the 
window  hii,5  controls  like  huttons  unci  dieck  boxes,  you  ^liuuld  me  the  Control 
Manager  to  scr  if  they  were  elieked.  Windows  with  ctmtroEs  are  better  handled  by 
the  Dialog  Manager,  tia  chapter  8  will  disciLSS. 

urlnDTag.  If  the  window  is  not  acMve  and  tlie  Open-Apple  key  is  not  tlown, 
TaskMilite'r  L-iilk  SelectWindow  to  activate  the  window.  It  then  oa.lls  DrafiWindow. 
which  causes  a  dotted  outline  of  the  window  tu  move  around  the  screen  as  the 
mouse  movesi  when  the  button  is  rdeastd.  the  sereen  is  redrawn  at  its  new  position. 
TaskMaster  then  exits  and  rfturns  a  nnll  e^  ent  eode.  If  the  window  is  active,  or  the 
Open-Apple  key  is  down,  SelectWindow  is  not  tailed  first. 

wlnGrow.  TaskMastcr  calls  GruwWmdow.  which  canscs  a  dotted  ontline  of  the 
window,  anchored  in  the  top  left  mmer,  to  move  in  cmicert  witli  the  mouse. 
GrowWindow  returns  the  new  diineniioiis  of"  the  window,  which  TaikMaster  passes 
to  SizeWiiidow  to  redraw  the  window.  TaskMastcr  then  exit-;  and  returns  a  null 
event  code. 

wInCoAtray,  Ta.skMaiter  calls  TrackCoAway  to  track  the  movement  of  the  mouJie 
until  the  button  is  relen.sed.  If  the  button  is  released  outside  of  the  close  box. 
TaskMa':tPr  exit';  and  returns  a  null  event  code;  otherwiie,  it  puts  the  window 
pointer  in  TaskData,  exits,  and  returns  a  wIiiGoAwa>'  event  code.  The  application 
can  then  cither  ijerniiinejilly  dispose  of  the  window  by  calling  CloseWindow  or  just 
temporarily  remove  it  Irom  the  screen  with  HideVVindow, 

ivlnZoom,  TaskMasler  calls  TrackZoom  to  track  the  movement  of  the  mouse  until 
the  button  is  released.  If  the  button  is  released  outside  of  the  zoom  box.  TaskMaster 
exits  and  returns  a  null  event  code.  Otherwiie,  it  ciills  ZoomWindow  to  resize  the 
window  to  its  zoomed  size  or,  if  the  window  has  already  been  zogmed,  to  its 
prezooined  stze^  TaskMaster  then  e^its  iiiid  returns  a  null  pvent  code. 

ifflnFrame.  If  the  w  indow  is  not  active,  TaskMaster  calls  SelectWindow  to  activate 
the  window,  exits,  and  returns  a  null  event  code.  If  the  window  is  active  and  the 
event  occurred  in  a  scroll  l>ar  th;it  is  part  of  the  windnw  frame,  TaskMaster  talis 
TraekControl  with  a  custom  control  action  protediire.  This  action  prncedure  per- 
forms necessary  scrolling  atid  updiitin^  of  the  window  by  calling  the  wContDetVroo 
procedure  that  was  defined  when  the  window  was  created.  TaskMa-ster  then  exits 
and  retunia  a  null  event  code.  Utbe  event  wccurred  in  some  other  part  of  the  frame, 
TaskMaster  e.idts  and  returns  the  wlnFrame  cnde. 
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wInDeak  and  lelnlnfo.  TasltMastcr  SncK  noihm^  special  Ftn-  these  two  t\peK  of 
events  ll  simply  places  the  window  pointer  in  TaskDahi  L.ind  vxits  with  thf  wInDesk 
or  winliifo  cndf.  as  the  case  may  be. 

DRAWING  IN  A  WINDOW 

Objects  are  draw^i  in  a  window  by  mnvin^  a  st>fhvare-L'ontnilk'd,  invisilile  ptn  cUrOund 
the  Screen  with  QuickDraw  fiiiiLliim^.  These  olijet'ts  u^ii  be  text  chariitlerSi,  ^t?0- 
metric  ybjects,  or  randum  scrihhlinHs.  Thi?'  pen  ha.s  severil  chdractt^ristics  that  an 
he  set  to  affpct  the  app^^arancf  cif  the  iihjeet  ht^i'ng  drawn ;  an  "ink-  color  and  pattern, 
a  size,  and  a  transfer  niode,  for  example. 

Note  that  whtii  you  draw  an  object,  only  the  bitii  for  the  pixels  which  fall  inside 
the  viitible  pLjrtit>n  of  the  einitent  region  are  aetuully  tnmsterred  to  the  t.'ontent 
region's  jneniorj'  urea.  OtJier  pistfis  are  ignured. 

The  lunftioiis  dtst^ussed  below  affect  only  the  active  QuickDraw  GrafPort,  which 
is  not  ne(.-esiari!y  the  active  window.  To  make  a  particnlar  Grafl^cirl  active  and  to 
adjust  tlie  coordinate  origin  of  the  CnifPurt  pruperly,  use  StartDrawing: 

PdshLong  MLndauPtr  ;Pointer   to  wiridoin 

_S  tartDrawL  ng 

You  need  to  call  StartDrawinR  only  when  you  are  drawing  outside  a  wContDefProc 
window  update  subroutine. 

If  you  do  nut  do  this,  youi  may  find  that  drawing  operationii  talce  place  in  an 
unexpected  window,  or  in  the  L-orreet  window  but  ^t  an  unexpected  position. 
StartDrawing  peribniis  its  function  by  talliup  Sell'ort  to  set  the  active  drawing  port 
and  SetOrigiii  to  set  the  origin  to  the  positton  indicated  by  the  values  of  the  window's 
scroll  controls 

Before  drawing  in  a  window,  it  is  a  good  idea  to  save  the  pointer  to  the  currently 
active  drawing  port  with  GelPort; 

PHfl  ispace  for  result 

PHA 

.GetPort 

PcjpLong  TtiePort 

Wheis  you  are  through  drawing,  you  tan  rejitore  the  original  port  with  SetFort: 

PLiihLcng  ThePort 
.SetPort 

It  is  especially  important  that  yt}u  do  thiN  in  a  multiwindiiw  envininment  to  ensure 
that  you  do  not  disrupt  other  drawing  operations. 
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Two  important  data  shruttures  you  will  use  quitf  often  with  QuickDraw  fiinttions 
arc  pointi  liild  rectangles.  A  point  is  innde  up  of  a  vertical  pusilion  and  a  liorizoiitaJ 
positian,  as  follows: 

Nj/Po  1  nt     D5     2  ^verticalpoaition 

□5     P  ihorirontalpositior 

Offsets  to  these  two  positions  (from  Myl'uinll  arc  givL-ii  the  lyraKnlic'  names  v  (0) 
and  h  {2}  in  itio  STANOAKD.ASM  Qink-  nitxlulf.  St»,  for  example,  to  laad  the 
Koriiuntal  positirm  into  tlit-  atciimnlatur.  you  could  use  llie  follnwinK  instruLtion: 

LDA  MypDinl+h 

A  rectangle  is  made  up  of  four  words  representing  the  position  of  (ht-  top  row.  the 
left  sidf,  thf  botlotn  rrjw,  and  the  risht  side; 


MyRecl       DS     2  5  top 

DS  2  jhottam 
DS     S  irlght 


The  standard  symbolic  niinies  for  offsi-ts  lo  llit^  four  tomponents  are  tnp  (G)^  left  (2), 
Wtiim  [4),  and  right  (6)  and  thty  arc-  iciuluded  in  the  STANDARD. ASM  L^ode 
rnodule . 

thai  you  inuAt  chanRt;  VidMnde  and  XMasClanip  in  the  STANDARD, ASM 
file  to  the  proper  values  for  the  super  hi>>h- resolution  mode  you  wajit  to  use.  For 
640-l>y-2tK;i  uukW.  «'t  tht-ni  to  $S0  and  640,  respectively.  For  320-by-2OO  mode,  set 
them  to  SWuud  .320. 

PATTERN'S  AND  COLORS 

A  pattrrn  is  an  H-hy-H  pixel  iinii^f  lliat  transierrt-d  lo  lhc>  sereen  uhi?n  lines  are 
drawn  or  shapes  are  painted  Lind  tilled-  \Vhen  a  pattern  is  drawn  in  a  window,  it  is 
blended  with  adjacent  piittems  lo  produce  a  smoolh,  regular  pattern  with  nn  aeani 
lines,  A  pattern  eiiii  alsn  he  a  solid  block  of  eolor.  enabling  you  to  draw  in  colors 
other  than  blaclk  and  white. 

Patterns  are  aetually  transferred  to  the  screen  only  after  being  proecssed  by  a 
maslc.  The  mask  is  an  H-hy-H  bit  inin};e  (not  a  pixfl  iniaKe)  that  specifies  whieh  pixels 
in  the  pattern  are  to  he  drawn  on  the  sereen.  Only  tho«;  pixels  in  the  H-by-S  pixel 
image  that  eories|>und  to  1  hits  in  ihe  8-hy-M  bit  mask  image  are  drawn.  Thi^i  means 
thai  if  the  mask  is  all  fur  f\aniple,  ihe  entire  pttltern  is  drawn  tn  the  screen, 
The  QuicltLJraw  hinetions  thai  dual  with  pattern;;  an-  *,umniarized  in  lnhle  6-4, 
A  patlem  is  "chunky"  m  ihat  each  pixel  is  associated  with  either  two  eolor  bits 
(640-by-2(K)  mode)  or  four  eolor  bits.  (320  by -201)  mode!.  Thus,  it  takei  eilher  16 
bytes  or  32  bytes  lo  tlefine  a  palleni.  depeiidtiiR  on  whieh  ^raphici  mode  is  active. 
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Table  6-4:    QuickDraw  Piittem-rclated  Functions 


F  unctio  n  Description 


Set  Pen  Pat 
GetPenPat 
SetSolidPenPat 
Set  Back  Pat 

CelBackPat 
SetSolidBackPat 
Solid  Pattern 

St'tPenMask 
Get  Pen  Mask 


Sets  the  pen  pattern  to  a  ipecified  pattern 

Returns  the  current  pen  pattern 

Sets  ttie  pen  pattern  to  a  iolid  color 

Sets  the  hackjjround  pattern  to  a  specified 
pattern 

Returns  the  current  background  pattern 

Sets  the  background  pattern  to  o  Mtlid  coJnr 

Fftiirns  the  pattern  L-orrespondinR  to  a 
solid  L'ulnr 

Sets  the  pen  mask  lu  a  specified  mask 
Return.^  the  current  pen  mask 


For  consistency,  however,  QuickDraw  ijJways  allocates  32  hytcs  fiir  a  pattern  in  640- 
hy-200  mndp'  the  second  jjroup  of  lb  bytes  is  simply  a  iliiplicate  tjl  the  fir^t  group- 
The  default  pen  patteni  is  a  solid  black  eoloi.  ll  can  he  changed  usinjf  Sf  tPenPaL: 

PuShPtr  ThePallerri         ;PoinIer  Id  pattern 
_SetPenPat 

RT5 

ThePattern  3^  M  '  3  01  0  1  0  1  0  1  '  ;Patterri  de^initiOTi 

A  related  function,  GetPcnPat,  is  called  in  the  same  way  and  fills  the  32  bytes  at 
ThePaltem  with  the  pattern  defmition. 

If  you  want  lo  set  thp  pen  pattern  to  a  solid  color  so  that  you  can  draw  in  color, 
use  SelSolidPenPat  instead: 

PjshWord  #CQlorNLim  iColor  number 

_SetSDLldPenPat 

The  colors  associated  with  each  culur  nujnber  were  given  in  table  6-1  at  the 
beginning  of  thi-i  chapter. 

The  djffercncf-  between  SetPtfuFat  and  SetSnlidPcnFat  is  that  you  pass  a  color 
number  to  SetSnlidPenPal.  nut  a  pattern  pointer.  QuiL'kDraw  takes  care  of  creating 
the  appropriate  pattern  fur  you,  The  color  luitnbcr  can  lie  0  to  15  for  32t)-by-2.00 
mode  or  0  tu  3  for  64O-bv-20O  mode. 
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If  you  uaiil  to  dctrniiiiiu  wlial  tlu'  patlL-rn  fur  a  solid  color  l<Mjks  like,  use 
SolidPattem: 

PiishWoi-d  #ColofNum       ^color  number 

PushPlr  The Pa ttern       [Pointer   to  pattern  spac e 

.SolidPattern. 

RTS 

ThePflttern  DS      3?       (Space  for  pattern 

A  bat-kgrniitid  jjatU'rn  is  tin-  paLleni  used  to  t-ra-se  iireas  of  a  window  or  draw  new 
areas  that  ^liiiil-  th(t>  vii-u  ,  Tin-  dtlVliill  hiitklinuiod  piittern  is  solid  white.  It  ciiii  be 
diiiiified  witli  Sc  lBacliHjl  and  Se-tSolidRackPat,  fiinclioiis  lliat  iirf  La]lt:d  in  the  same 
svay  as  Stll'enPat  and  S*-ISolidHc-nPat.  There  is  idsu  a  CclBackPat  function  for 
deleniliriinfi  what  the  tnirrent  bat  ksroiiml  pattern  is. 

SETTING  L'P  THE  DRAWING  PEN 

Refare  you  start  driiwinj;  text  in  <i  window,  you  must  set  the  pt-o  position,  This  is 
the  location  at  whidi  tt"^\t  tlritwing  will  bej;ii3.  Thtre  are  two  QoiL-kDraw  lunttiLins 
for  esplitilly  srttin^  tlit-  pen  |w>sition:  MmeTo  and  Move. 

Movi^To  mov't^s  the  pea  position  ttj 'd  Jipetiht:  point  in  the  l<ic^l  LOOrdinate  system 
of  the  window.  To  use  il.  pvish  ihe  liorizoiiUtI  iind  ve  rticil  tcHnponents  of  the 
coordinate  mi  the  staek; 

Puaht^ord  #2'  ;  HoriionlaJposiIiQn 

PlishWord'  #10  jVeflicaL  position 

_Ro«eTQ 

If  wu  wish,  you  can  eomhine  tbf  two  PushWord  operalions  into  u  single  I'uiihlxing. 
This  is  handy  if  tht  point  to  whidi  you  waul  tu  inov  i.-  is  ilrt'ady  stored  in  ineinor)-. 
For  exampk'.  -lappose  CelNe.\tEvent  or  TaskMaster  returns  a  butttin-down  event 
in  the  content  reKiciii  of  a  winduw,  To  move  the  pen  position  tu  the  point  specified 
tn  the  Where  field  of  tlie  event  record,  use  the  iiillowing  siibroutiiieL 

PushLong  Where 

_^Glat].a  L  ToLocfl  1  ;Swilch   to    local  coordinates 

PusliLoTig  bJtiere  ;Thi5  puaKes  h   then  v 

_Mo-veTo 

RTS 

Notice  that  because  TaskMaster  and  GetNextEveiit  return  a  global  coordinate,  that 
coordinate  must  be  converted  to  a  Itical  tioordinate  for  the  currently  active  window 
before  calling  MoveTo- 

Whcn  QuiekDrnw  draws  a  text  character,  the  current  vertical  pen  coardinate 
becomes  the  baseline  for  the  iort.  Because  characters  rise  above  the  baseline,  you 
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should  not  speciFy  a  verlkal  L-iiiirdinale  of  0  for  MoveTo:  il  you  do,  you  wQ]  see  only 
the  descenders  ol  the  chtiriicters  on  tlie  Brsl  line  when  you  start  drawing. 

The  Move  function  moves  the  pen  kxatioii  in  a  relative  way.  That  is.  with  it  you 
can  move  the  pen  sn  inaiiv  pixels  horizdii tally  and  vertically  from  the  current  pen 
Incatiiin.  Fur  inataiice,  if  you  want  lu  dnip  down  to  tlit'  iiest  text  line  in  the  v\indow 
without  changing  ihc  horizontal  position  (a  line-fee'd  operation),  use  (he  following 
code  segment: 

PushWord  #0  ;Horizontsl   d  i  ap  L  acemcTit 

Pu5hUor  d  #5  i^'er-tical  displace  me  nt 

A  Value  «f  9  \s  used  fur  the*  vertical  displacement  because  this  is  the  height  nf  the 
Syslt'iii  fdiil.  Yiju  can  ca,|fu!a1c  thi^  n.sini;  the  CflFonllilfu  function  (a^  drscrii>cd 

behiw).  Nnte  that  positive  horiznntal  displacement.'^  are  to  the  right  and  pmsitive 
vertical  displaccincnfs  Arc  downward. 

To  dftcnniiic  the  current  pusitinn  uf  the  pen,  perhaps  to  see  if  you  arc  still  inside 
the  window's  content  re;Kion,  u%c  (JetPcn; 

Pu3t)Ptr    TtiePpiTit  iPoifiter    to  point 

_GetPeri 

RT5 

TKePolTit  DS  4  ;v,   h  position 

GetPen  returns  the  position  in  the  local  coordinates  of  the  current  CrafPort. 

Setting  the  Pen  State 

¥oii  rnav  want  to  set  several  ullier  pen  cbaraeterijutici  betore  hefTjnniji);  to  draw 
graphics.  (The  functions  described  below  do  nut  afl'ect  text  drawing  operations. )  The 
important  tharacleriatics  are: 

■  The  pen  size 

■  The  pen  transier  nioile 

•  The  pen  drawing  patteni 

•  Tlic  pen  masli 

These  four  values  are  said  to  dehne  the  t^eri  stale.  You  can  determine  all  their  values 
at  once  using  CetPenState: 

PustiPtr  P5_Record         ;Ptr  to  pen  state  record 

_G.ptPer5tate 
RT3 
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PS_Record 

flNOP 

PtiLoc 

DS 

pos it  1  on 

[ poi nt ) 

PnSlis 

D3 

2 

Pen 

height 

DS 

2 

Pen 

width 

Pntlode 

D5 

2 

Pen 

mode 

PnPat 

DS 

32 

Pen 

pattern 

D5 

8 

Pen 

ma  5^ 

The  parameter  tah>  pasyed  to  GctPcnSlatt-  is  c-alled  a  pcB  state  record 
To  chaiipe  the  im.'ii  .st:ite,  use  the  folUming  functions; 

•  SetPenSize 

•  SetPenMode 

•  SetPeiiPat  (descrihecl  above] 

■  SelPenMask  t(5t:!ic'ril>ed  above) 

•  SftPenState 

The  size  of  the  pen  refers  to  the  height  and  uidth  of  its  nib.  This  nib  hanps  down 
and  to  the  right  of  the  ourrent  pen  position.  To  change  the  pen  size,  say  to  3  pixels 
by  5  pixels,  use  SctPenSize: 

PuahHord  #3  -iNew  width   in  pixels 

PuahWord  #S  ;Naw  height    in  pi>rp]5 

.SetPcTiSlze 

You  can  determine  the  current  pen  size  witli  CetPenSj2e: 

PushPt  1"  P*nS  I  zeLoc      jPointer    to   result  space 
.GetPenSwE 

RTS 

PenSiicLoc     DS  4 
GetPenSiifi  returns  the  width  and  height  at  PenSizeLoe. 

The  pen  mode  refers  to  the  way  in  whieh  QniekDraw  combiner  the  pattern  flowing 
out  of  the  pen  with  the  pixels  on  the  screen.  The  result  nf  the  combination  is 
displayed  on  the  screen.  The  different  mcxles  are  summariz.t'd  in  table  6-3.  (Note 
that  some  of  these  modes  are  for  text  dravvinji  only.) 

To  change  se\x  lal  pen  eharacterlstics  at  onee,  call  SetPenState  by  passing  it  a 
pointer  to  s.  fil|.ed-in  pen  state  rectird. 

If  you  have  thanRed  several  pen  character  is  tics  and  you  want  to  return  to  the 
standard  pen  state,  call  PenNnrmid  [no  parameters).  It  sets  the  pen  size  to  1  by  i, 
the  pen  mode  to  COPY,  the  pen  pattern  to  hlack,  and  the  pen  mask  to  all  Is. 
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Table  6-5:    The  QuiLkDraw  Transfer  Modes 


Transfer  Mode 


Symbolic 
Name 


Description 


SOOOC] 
$0001 
$0002 

$000,3 

$0004 
$0005 
$0006 
$0007 

$S000 
$8001 
$8002 


C:OPY 
OK 
XOR 
BIC 

foreCOPY 
foreOR 
ft>reXOR 
fore  BIC 

notCOPY 

natOK 

noLVOR 


Pixels  are  copied  directly  to  th' 
scrern. 

Pixels  are  logically  ORed  with 
the  screen  pixels,. 

Pixels  are  logicsdly  exclusive- 
ORed  with  the  screen  pixels. 

Piiel  biti  which  are  bet  to  1 
cause  ciirrespondinj^  pixels  On 
the  screen  to  be  t-leared  to  0 

Text  onttj:    Foreground  pixels 
art  copied  directly  to  the 
screen 

Text  oniy:    Foreground  pixels 
ar?  logically  ORcd  with  the 
screen  pixels. 

Ti^xt  only:    Foreground  pixels 
aj'*."  logically  exclosivc-ORcd 
with  the  Screen  pixels, 

Text  only.     Forej^rtiuncl  pixel 
bits  which  are  set  tu  I  caose 
corresponding  pixel  bits  on  the 
screen  to  be  cleared  to  0. 

The  pen  patteni  or  text  is 
invprted.  then  copied  directly 
to  the  screen. 

The  pen  pattern  or  text  is 
inverted,  then  ORed  with  the 
screen  pixels. 

The  pen  pattern  nr  test 
inverted,  then  lugicillly 
exclusive -ORed  with  the  screei 
pixels. 
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Table  6-^:  Continui,'d 


Tramfvr  Mode 
S8003 


?8007 


Scimbotic 
Name 


niitBIC 


notTnri-COrY 


nutturt-OK 


nutlbreXOR 


nolforeBIC 


Description 


The  pen  pattern  or  Icxl  is 
inv<:rled.  then  those  piscl  bits 
whicli  are  set  to  1  cijiis(" 
airrespondiiig  pisHs  tm  the 
screen  to  he  cleared  t(i  I). 

Text  only:    The  character 
rectangle  is  inverted,  and  the' 
pixels  that  are  im  art  mpUfd 
directly  to  (he  scrct-'n. 

Text  oniy:    The  tharatfcer 
rectangle  is  invfrtt'd,  and  the 
haclcgroiind  pixels  arc  Icjgically 
ORed  wttti  the  screen  pixels. 

Text  iinhj:    The  character 
rectantfle  is  inverted,  ttnd  the 
backyrciund  pixels  iire  logieally 
excIusivc-ORed  with  the  SLreeii 
pixels. 

Text  nnly:    The  character 
rectangle  is  inverted,  and  tlie 
hat'kgrijund  pixels  which  are  set 
to  1  cause  cxirrespondiiis  pb;el 
hits  tin  the  screen  to  be  cleared 
toO. 


FONT  CHABACTERISTICS 

A  font  is  a  set  nf  characters  having  (he  saine  general  Drnameiital  design.  One  font, 
called  the  systtni  ftmt,  is  stored  in  ihc  GS  Rf)M  and  is  always  availahle  for  use  hy 
the  QuickDraw  text-drawiiif;  ilinctlons.  Other  ftiiits  may  be  defined  and  stored  in 
the  SYSTEM/FONT15/  subdirectory  on  the  botit  disk.  Thev  can  be  loaded  into 
memory  and  made  available  tii  an  application  usinfj  the  Fuot  Manager,  QMiekDraw 
can  draw  characters  in  any  availabl^e  font,  but  it  will  use  the  system  font  unless  you 
s|jccif>'  other^vi^e. 

.\lthouyh  "QuickDraw  has  a  few  fdnt-relaled  funetions,  you  should  use  the  mure 
poweriul  Font  Manager  I'lloctiOTls  instead.  To  start  up  the  Font  Manager,  use 
FM  Startup; 
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PushWord  DPflddr 
_rM5  tar  t  up 


sProgram  ID  (from  MMStartLip) 
;Addre5&    of    ore  pa9^    ifi    bank  SOO 


The-  FcMil  MaiiHRt-r  re<|uires  Hie  pro^eTicc  nf  innst  rs  hiol  wts,  indndin^  the  nirely- 
useti  List  Miiiiiifier,  Make  sure  tlicy  ai-p  all  luatk-d  Wfort-  L'billiii>>;  FMStartup. 

FMStartup  scans  the  SYSTEM/FONTS/  Mihtiirc.-c:tijry  of  the  boot  disk  and  makes 
a  list  of  the  Font  liitnihcs  il  finds  there  A  f-»nt  GimiK  is  a  f^eneriil  foiU  type  such  sls 
Helvetica,  Courier,  or  Vfnlcc,  The'  dflauk  systt'm  liint  is  called  Shaston. 

A  font  of  a  pEirticular  family,  sixc.  and  style  is  dt^scribed  by  a  fontID  long  word. 
Here  is  its  stifucture: 


■  hits  [)0-l5  r  fnnt  family  niiml>er 

•  bits  16-23  :  font  style  byte 

•  hits  S4-31  :  font  size  byte 


The  family  mimtier  is  the  number  the  Font  Manager  asj^igiis  to  the  font  when  it 
puts  the  font  in  its  font  list.  Bit?,  in  the  s^tyle  byle  affect  the  style  of  the  fnnt  ihnld, 
itahc,  rindcrhnp,  outline,  cjr  ihaduw};  style  bytes  are  described  below  in  ihe  diseus- 
sion  oFSetTextFace-  The  fimt  siw  is  the  point  size  of  the  font  [1  point  -  1/72  of  an 
inthl- 

The  user  (idu  install  ii  new  fbiil  relatively  easily,  at  least  if  the  applitation  ealls 
ChooscFont  to  bring  up  a  standard  font  seletlion  dialog  box: 


PHA 

PHA 

PushLong  TheFontlD 
PushUortf  #0 
_ChDoaeF  DTI  t 
PopLong  NewFontID 


;  spac  e   for  result 

jfontID  of  current  font 
■0   -    liEl  all  fonts 

;EG5ult    15  HEW  fanllD 


Push  zero  instead  of  TheFoiitlD  to  select  the  system  Font. 

The  fi)rni  of  the  Icint  selection  diiilog  bos  i,s  shown  in  lijiiirc  fi-S,  It  eonsi:it:i  of  3 
•icrulLbL'  window  that  holds  a  list  ol  font  uinnes  for  SH.-Ii'clinn,  eheckbuxes  for 
seletlinfi  tlie  font  style,  and  tl  scrolhble  window  that  hnhh  a  list  of  point  sines  that 
are  available.  There  is  also  an  edit  box  for  typing  ni  any  other  point  size  to  which  a 
font  should  be  Jitaled;  scaled  fonts  can  look  ragH*"d,  however. 

ChooseFont  returns  the  fonllD  for  the  font  selected,  or  0  if  the  dialog  box  was 
canceled. 
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Figure  6-8.     TIk?  Font- select  ion  Dialog  Box 


ont: 
Courier 
Genevo 
MilveticQ 


Times 
Venice 

Stale: 


Plain 

□  Bold 

□  italic 

□  Underline 

□  Outline 

□  Shadow 


Size: 


Other 
Size: 


HI 


[Cancel) 


OK 
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Fieure  6-9.     Thf  Charat-tt^risMcs  »f  an  Apple  lies  Font 


ascent 


c 


Une 


To  make  the  stfl^.'t^tl-^^  font  the  turrt-nt  font,  so  that  it  will  h*-  used  by  QuitkOraw 
tfxt  drawing  fmichnns,  Ciill  Iii^itaUFimt: 

PuahLong  NpwPoTitlD  ifonllD  of  desiped  font 

PushWofd  #D  jO  =  enable  scaling 

_Inatal]Fqnit 

The  iitcoml  parameter  f^cintrnls  whether  font  scaling  is  enabled,  If  hit  0  is  1,  scaling 
is  not  enabled. 

Wlien  ynu  are  through  using  the  new  font,  yun  fsii  make  the  system  font  the 
ctirrecit  frint  again  with  tlie  LnadSysFoiit  funL'tion  {no  parameters).  If  yow  are  never 
going  to  use?  the  new  font  a^niii.  make  it  purf;cfahlr  with  SetPurgeStat; 

PuahLong  NtwfantlD  :fontlD  Qf  font 

PuihUijrd  #SO0Q10DOO  ;bit   4  -    1  (purge) 

_Se-tPurge5tat 

Bit  4  of  the  Sietund  parameter  L-oiitruls  wlicther  the  iipeeified  font  is  to  be  purgcable 
(1)  OT  not  purReahlc  (0). 

Font  DefLurtioiis 

As  shown  in  figure  6-9,  each  character  in  a  font  is  defined  inside  a  rectangular  grid, 
called  the  frmt  rf  ctang,k.  wJiith  endujues  the  larsefit  chiiracter  in  the  font.  Another 
rectangle,  the  character  reclanflU;  is  the  smallest  rectangle  that  can  enclose  the 
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outline  of  the  charactrr.  The  size  nf  this  rectanjile  will  vary,  tlependin^^  on  the  size 
of  the  character. 

Thost?  pnints  in  a  tharau'tcr  rccUngl*:  that  are  highlighted  use  caJled  foreground 
points,  hecause  they  define  the  actuaJ  shape  af  the  etiaraeter.  The  other  points  are 
backgroiinri  pnints,  Whfn  a  c-haiaeter  ii  transferred  to  a  GraflPort,  tht  Foreground 
puints  hecfJDie  hlac^k  pixels  and  the  hackground  puiiits  lift-rtme  while  pixels,  although 
ygu  can  thanec  tht'st*  default  mlors  with  SetUatkColur  and  SetForeColor  if  you 
wish.  The  ciilorH  art"  defiiietl  l>y  either  a  2-ljil  inuitber  ■ffi-lO-by-StKl  mode)  or  a  4-bit 
number  (320-hy-2lX)  mode),  su  there  art;  either  Ibur  or  sixteen  colors  to  choose  from. 

Bach  charaeter  in  a  funt  is  defined  relative  to  two  reference  points,  the  baseline 
and  the  charcictfr  i>rij£iii.  The  baseline  i.s  an  imaginary  line  on  which  the  character 
rests;  it  sen-es  muth  the  Same  purpose  as  &  line  Oil  a  piece  of  iiotepapor.  The  number 
of  pixel  lines  Iwtween  the  has*?line  and  the  top  of  the  font  rectangle  is  the  ascent. 
The  number  of  lines  between  the  baseline  and  the  bottom  of  the  font  rcttanEjIe  is 
the  discent — this  where  the  deawmders  of  characters  such  as  g,  y,  j,  p,  and  q 
appear. 

'fhe  character  origin  marks  the  jwsition  in  the  character  rectangl''  that  is  ahgned 
with  the  pen  ptf.sition  before  tile  cliarrtctcr  is  drawn.  The  viidMax  of  a  font  is  the 
majtiinum  numher  of  pixels  between  the  characteir  origins  of  two  successivp  char- 
acters. For  a  propDrlional  font,  such  as  the  syMcni  font,  the  actual  widths  of  most 
characters  are  less  than  this,  You  can.  however,  tell  Quiekl3raw  to  draw  system  funt 
characters  that  are  all  widMax  pixels  wide  using  SetFrintFlaas: 

Pu^hLJord  #1  ;1   =  f  1  xed-wid t h ,   0  =propar  1 1  ana  1 

_5etFort  Flags 

Tti  return  to  prnportioual  mode,  pass  a  0  to  SetKontFla^S,  Vnu  probably  will  not 
use  fixed-width  characters  very  often,  however,  becaitse  the  paps  between  characters 
are  lar|;e  and  unsijihtly.  Yon  ;dso  cannot  fit  as  many  characters  across  the  width  of 
the  screen. 

The  leading  nf  a  font  is  defined  as  the  niiiiiber  of  blank  line,*)  between  the  descent 
line  and  the  l^ittom  of  the  hint  rectauRle.  This  area  act.s  as  a  spacer  between 
suLcessive  linei,  of  texl.  GetFonthilo  rettirns  the  ascent,  descent.  widMa*;,  and 
leading  of  the  currently  active  font  ill  a  four-word  font  information  record.  For  the 
syjitem  ftint,  the  results  are  as  follows: 

•  ascent  7 

■  descent  1 

■  widVlaj!  12 

*  leading  J 
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The  subroutine  below,  wlikh  iritorporates  Gc-tFontlnfo,  can  be  used  to  move  the 
pen  position  to  the  nrxt  IIiil-  it!  thf  vviriilow; 


V 

GEQU 

a 

Jl^'-J  ^-f-f^^t 

'jve'^'ical    tipid  ciiset 

CRLF 

5TART 

PuihPtr 

F  1  Record 

iPointer    to    fort  record 

_  5etf  pn 

t  tnHo 

CLC 

LDifl 

fi  5cen  t 

ADC 

Des  cen  t 

AD'C 

5Tfl 

FoTitHp  1  jhl 

PiishPlr 

PenPaa 

!  Pointer   to  a  pa i nt 

_GetPen 

;Get  current    pem  position 

CLC 

LDfl 

PrnPas+v 

jGet  currerit  vertical 

flDC 

Font  Heigh  t 

;  Add   I  line  he  i  gh  t 

PER 

jhoriicntfll    (Is'ft  edge) 

PHft 

;vertical    (rexl  line) 

RTS 

F  1  Record 

ANOP 

^Fofit    i  nf  orma  t  Ion  record 

Ascent 

D5 

2 

Descen I 

DS 

D5 

Leading 

DS 

pDTilHeighl 

D5 

2 

PenPos 

;polnt  (*/,h) 

END 


This  siihrnutinc  adds  astent,  dfisccnt.  and  leaditiR  toticihfr  In  ualoulate  the  Keijjht 
of  the  font.  It  then  iidds.  llie  height  to  the  current  vertical  pen  position  to  cirtrrmiine 
the  vertit-al  position  of  thf  next  haseline.  Finally,  it  calls  VIoveTo  to  [xisition  the 
pen  at  the  left  side  uf  this  line. 

You  can  ^ssif^n  certain  typefaee  attrihutes  to  a  I'nnt  using  the  SetTextFace  function. 
The  hvv  attnhutes  currently  dcfinc-d  are  hold,  itahf.  imdtrline,  outline,  or  shadow 
or  any  combination  of  the  five.  Bits  in  tlie  word  parameter  passed  to  SetTextFaee 
correspond  to  attributes  a-i  shown  in  fifcure  6-10-  If  all  the  bits  are  fl,  the  typeface 
is  ca]led  plain. 

For  example,  to  switch  the  typefate  to  bold,  execute  the  following  code  sepneut; 

PushWord  #lL0ODQDt)01  textface  word 

SelTei:  t  Face 
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Figure  6-10.     TIm-  Shit-  Byte  I  .scil  liv  SLETt-xtPLtn- 


7 

6 

5 

4 

3 

2 

1 

0 

not  used 


botd 

jtsfjc 
underline 


Note  that  stiine  itnit*i.  niL'liidiii^  ihi-  !iy>it<-iii  font,  may  mit  support  all  (if  these 
attributes, 

GelTejttKace  retumii  the  current  lextfiiee  word: 

PHA  5paceforre5uJt 
_tetTexlFace 

PLft  iGel    the  result 

DBAWINC  CHARACTERS 

To  print  a  iin^lc  eharactiT  in  a  window,  [Mihition  thf  pen  M^itli  Move  or  MoveTo. 
Then  push  the  ASCII  t-ode       llie  ehanieter  un  llie  stack  and  eall  Drav^^Char: 

PiishUlord    ^ft-n  ;ASCI]    code    for  "A" 

_DrawChflr 

As  in  all  QuickDraw  text  drawhig  functions,  the  ASCII  code  fnr  standard  eharat'tt-rji 
must  have  hit  7  tleared  tu  0.  See  appendix  I  for  a  [Icscription  (if  thr  ASCII  eiieudin^ 
schcmr.  The  system  font  lusi^ns  variuns  iiircijin  charatlfrs,  nunietarj-  .'iymlid.s,  and 
common  icons  to  the  I2S  codfs  that  have  hi!  7  set  Iq  L- 

Tliere  are  throe  ri-ther  "Draw  liinL'ti»ns  for  drawing  sfCiiieneeS  of  t'harACtefS  Stored 
in  memory]  DrawStiIng,  l^rawCStrinj;,  and  DrawTest,  The  ime  to  use  depends  on 
whether  the  sequence  begins  with  a  length  Iiyte  (h  FasLal-tyjie  strinpl.  ends  with  a 
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zerri  byte  (a  C -typL-  string),  cir  is  an  arbstrar>'  seciuence  of  characters  with  no  length 
iiulicatt>r  (text), 

Tlircp  subroufines  showing  how  to  use  these  dmwing  funrtioiis  are  ^ivL-u  below: 


DrawSubl        Pu^hPtr-  MyPStrirg 
_DrflwStr  ing 
BTS 


iPbinter    to  airing 


Dr  awSuhl        PushPtr  MyCSlr ing 
_DrswCS  t  r  i  rug 
RTS 


; Po I r t er    lo  st  r 1 ng 


PuahPtr  MyText 

_DrawTe)(  t 
RTS 


;Pointer  to  string 
;  length 


MyPSUing     DC       11  '1G'  ;length 

DC      C'A  Pa seal   string.'      ;the  characters 


MyCStrmg     DC       C'A  C  string,  i  ;  the  characters 

p[;         [  1  '  0  "  1  tra  1  1  1  ng  00 


MyTejct  DC       C'This   i9  a  tesit  string.' 

NotiL-e  that  for  DrawTt-xt.  ymt  iiU-nlily  the  portion  ol  the  text  ta  he  displayed  by 
^petifyiiig  a  .^tjirtiiiS  position  and  the  luimber  of  fhsiratters  vv-ith  which  you  want  tn 
w.irlv.  This  is  nol  iicfi  SHan  lor  DriiwStrtng  or  DliiwCStriiig.  hetausc  thf  length  is 
kntmii  and  the  entire  striiiR  is  aKvays  printed. 

If  yon  use  Pastal-tvpe  ^lrin|;.s  quite  often,  you  will  find  it  ccinveni<'nt  to  define 
them  with  a  macro  cailed  STB,  STli  is  nscful  because  it  iUUcmmtieally  calculates  the 
leiifjth  of  the  siring  and  iiiscrt-'i  it  before  the  string's  character  codc,^,  You  do  nut 
have  to  count  the  chdractor?;  yourself.  Here  is  hnw  lo  define  the  string  "A  Pascal 
string"  n.sinfi  STB  instf  ad  of  two  DC  directives^ 

nyPStfing  5TR    'A  PaBcal  string' 

A  definition  for  the  STK  macro  is  given  in  Usling  6^3- 

is  is  nnjiortiint  to  realize  thai  the  pen  position  automaHcally  advances  along  the 
line  as  you  draw  c:haracter^.  There  is  no  need  to  set  it  explicitly  ^vith  Move  or 
MovcTg  unless  ycm  want  to  move  tt>  ajiother  line  or  to  ii  non-adjacent  position  on 
tJie  SLUiic  line. 
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Note  (hat  nune  of  the  Eext-drawins  functions  react  to  tontml  characters  in  standard 
ways.  If  vou  pass  a  Lirfiagr  r<-tuni  cndt-  (SOD)  H)  DrawChiir.  for  example,  the 
drawing  ijosition  does  not  automatically  move  to  tlie  left  side  of  the  nt^xl  line  in  a 
window;  instead,  an  inverse  question  mark  character  appears  on  the  screen  (indi- 
(.■ating  that  tliere  is  no  symbol  for  the  character  in  tlie  fon!  definition),  It  is  up  to 
the  application  to  iiitert;ept  cgntrol  characters  ajid  handle  thtm  appropriately. 


Text  Mea&urbg 

It  is  often  convenient  to  krnnw  the  width  of  a  character,  or  a  series  of  characters, 
before  drawing.  Knowing  the  width,  you  uan  easily  tenter  the  text  or  determine  if 
there  will  be  enou^  room  to  display  it  un  the  current  hne.  The  program  in  listing 
6-4  shows  how  to  center  a  Une  of  text  in  a  window,  for  example. 

QuitkDraw  has  a  set  of  text  measuring  functions  you  can  use  to  determine  widdis: 

■  CharWidth  (for  a  single  character) 

•  TextWidth  {for  a  sequence  of  charaetei-s) 

■  StringWtdtK  (lor  a  string  preceded  by  a  length  byle) 

•  CStringWidth  (for  a  string  Ebltowed  hy  a  SOO  byte) 


To  use  these  funttiuns,  first  posh  a  dummy  word  on  the  stack  to  reserve  space  for 
the  result  (the  width  in  pixels),  and  then  push  the  ASCII  code  for  the  character 
(CharWidth)  or  a  pointer  (o  the  text  or  string  (TextWidth.  StringWidth. 
CStringWidth)  For  TcxtVV'idth.  you  must  also  push  the  length  of  the  text  strinfi. 
Fmally,  call  the  function  and  pop  the  result  from  Uie  slack. 


Test  Color 

Using  SetForeCoIor  and  SctBackCoIor,  you  can  set  the  foreground  and  hackground 
color  of  text  you  draw  in  a  window.  Both  require  a  parameter  word  that  contains 
the  color  number  to  which  you  want  to  switch.  In  64CI-by-200  mode,  this  number 
can  be  0  to  3;  for  320-by-20U  mode,  it  can  be  0  to  15. 
Here  is  bow  to  use  SetForeCoIor  and  SetBackColor; 

PuShWocd  #ColorHuir  -Pa^h  new  color  number 

_SetroreColor  ;  (or  Se  iBac  ItCo  1  or  > 

To  determine  the  current  color  characteristics  of  the  font,  use  GetForeColor  and 
GetBaekColor  They  return  the  color  number  on  the  stack: 
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pHfl  J  apace  for   resul t 

_OetBflc  kCo 1  or 

PLfl 

STfl  TheCalor  ipop   Ihe  result 

The  default  background  and  foreground  colors  are  white  and  black,  respectively. 

The  program  in  listing  6-5  ahow.i  how  to  display  text  in  all  16  culors  in  320-by- 
200  mod^  usiiip  SctForeCnlnr. 

Transfer  Modes  for  Text 

A  transfer  mode  refers  to  the  technique  QuickDraw  uses  to  draw  a  text  character 
on  the  screen.  The  mode  defines  how  QuickDrsiw  is  to  combine  a  pixel  in  tlie 
character  with  the  corresponding  pixel  in  the  scrc-en  buffer. 

The  possible  transfer  modes  were  described  m  table  S-5.  The  default  mode  is 
COPY,  which  causirs  the  pixels  in  th*'  character  rectangle  to  replace  the  correspond- 
ing pixels  on  the  screen 

Another  particularlv  usehil  mode  fureXOR.  if  you  u^e  this  mode,  you  can  draw 
text  on  any  background,  and  then  erase  the  text  and  redraw  the  backsround  simply 
by  redrawing  the  text  again  at  the  same  pos^ition. 

To  set  the  transfer  mode,  use  SctTextMode: 

PushUord  #TBxtno.cle  ;TbxV   transfer  mcde  code 

_SelTertriQde 

You  can  determine  what  the  currently  active  mode  is  using  GetTextMode: 

PHA  ;^pace  foi^  result 

.GetTtxtMode 

PLfl 

STfl  TheMode  [Pop  ttie  mode  code 

It  is  hard  to  visualize  the  effect  of  some  of  the  transfer  modes.  IC  is  best  to  write  a 
short  prof^ram  that  uses  different  iTKxles  to  draw  text  on  differently  colored  back- 
grounds. 

DRAWING  UNES  AND  SHAPES 

QuickDraw  has  several  fiinction-s  for  drawing  objects  other  thsn  characters  or  text 
strings,  You  can  use  thfse  functions  to  draw  lines,  rectangles,  arbitrarj'  regions, 
polygons,  ovals,  round  rectangles,  and  arcs. 
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Lines 

You  can  draw  straiclil  lines  with  the  Line  and  LinpTn  Funetions,  LineTo  draws  a 
line  from  the  current  jltn  loeation  to  ihe  spccifif^fl  pnint: 

Push  Wo  rd  #43  ;Hori.2Dntal  poaition 

Pu^tiUor d  ;Vertical  position 

_LinETo  ;Draw  the  line 

Wilh  Line  ynn  ean  draw  a  line  tliat  tenninates  al  a  iMsitjoti  that  is  relative  to  the 
current  pen  pnsitinn: 

PushWord  #10  iHgrijontai    displace me nt 

PushWord  #S  ;Vei'tLCfll  displacement 

Lire 


Positive  hfiriznntal  displacemtnts  move  the  pen  tn  the  right.  Positive  vertical  dis- 
placemfrnts  mo^'r  if  d{iwn. 

After  cither  Line  i;r  LineTo  is  ealled,  the  pen  position  moves  to  the  end  of  the 
new  line. 


Shapes 

QuickDraw  uses  five  fundamental  drawin)4  operations  to  manipulate  the  shapes  it 
supports; 

FfEiming — ilrawing  iin  Dutliiie  of  the  shape. 

Paiiiting — filhriff  tht^  interior  of  a  shape  witli  the  turrent  pen  pattt^m.  You  ein 
set  the  pattern  to  a  particular  ciihjr  u-sin^  SetSolidi'enPat  or  to  uny  arbitrary 
pattern  usinj;  SetPt"nPal. 

Erasing — replacing  (he  interior  tjf  a  .'ihape  wilh  the  background  pattn^rn.  Ytm 
cati  set  the  background  pattern  u-^inj-  SetSolidBaekFat  or  SetBackPat- 

Invertin^ — inverting  the  pixels  inside  a  shapp. 

Filling — filling  the  ijiterior  oi  a  shape  with  a  specified  pattern. 

The  spetific  shape-drawing  functions  for  objects  arc  summarized  in  table  6-6. 


Drawing  Lines  and  Shapes  203 


Table  6—6;     QuiekDmw  11  Shape-ilrawing  Functions 


Function 


Descrijition 


FrameRect 
FrameRpn 
FrameFoly 
FraineOval 
FrameRReut 
Frame  Art- 
Pain  tRect 

PaintRgn 

PaintFoiy 

PiiintOval 

PainlRRcct 

PainlArt' 

Erase  Reut 

EraseRRn 

Erase  Poly 

EraseOval 

E  rase  R  Rett 

EraseAre 


Draws  the  outline  nf  a  rettanKle 

Draws  bhe  outline  uf  a  reginn 

Draws  tlie  nutline  of  a  polypon 

Draws  the  outline  ol  aii  oval 

Draws  the  outline  of  a  raund  rectangle 

Draws  the  outline  of  an  ate 

Fills  the  interior  of  a  ret-taii^ie  with 
!he  turrent  pen  patlern 

Fills  the  interior  of  a  region  with  the 
current  pen  pattern 

Fills  the  interior  of  a  polygon  with  the 
Lum:nt  pfn  pattern 

FilK  the  interior  of  sn  oval  with  the 
■current  pen  pattern 

Fills  the  interior  of  a  miind  rectangle 
with  the  current  pen  pattern 

Fills  the  interinr  of  an  arc  [a  wedge) 
with  the  L'lirrL'nt  jk^u  patttTH 

Fills  the  interior  of  a,  rectangle  with 
the  ttirrt-nt  hack^round  pattern 

Fills  the  interior  of  a  region  with  th*; 
current  haek^ound  patt*?m 

Fills  the  interior  of  a,  poIyf!ini  \vHh  the 
ciirrenl  Ijiitkjirtnind  patt!?rn 

Fills  the  interior  of  an  oval  with  the 
current  background  ptitEem 

Fills  the  iiJterior  of  a  round  rectangle 
with  the  current  hatkjiround  pattern 

Fills  the  interior  of  An  are  ta  wedse) 
with  the  current  haekj^ruund  pattern 
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Table  6—6:  Continued 


Function 


Descriptiim 


InvertRect 

InvertRgn 

Invert  Poly 

InverlOvaJ 

InvertRRecl 

InvertArc 

FillRect 

FillRgn 

FiliPoty 

FiUOval 

FillRRect 


FiUA 


rc 


Inverts  the  pixels  in  a  rectangle 

Inverts  the  pixels  in  a  region 

Inverts  the  pixels  in  a  pnlygnn 

Inverts  the  pixels  in  an  uva] 

Inverts  the  pixels  in  a  ruund  rectangle 

Inverts  the  pixels  in  an  art  (Tlie  arc  is 
defined  by  a  sti^xling  an^le  and  an 
angular  extent.) 

Fills  the  interior  of  a  rectangle  \Wth  3 
specified  pattern 

Fills  ihc  interior  of  a  region  with  a 
specified  pattern 

Fills  the  interior  of  a  polygon  with  a 
specified  pattern 

Filh  the  inlcnor  of  an  oval  with  a 
specified  pattern 

Fills  the  interior  of  a  round  rectangle 
with  a  specified  pattern  [The 
curvature  of  the  comers  can  also  be 
set,* 

Fills  the  interior  of  an  arc  with  a 
specified  pattern  [The  arc  is  defined 
by  a  starting  angle  and  an  angular 
extent.) 


To  draw  the  outline  of  a  rectangle  in  a  window,  call  FrameRec!t  hy  passing  a  pninter 
to  the  definition  of  the  rectangle: 


PdshPtr  ThsRcct 
_  rrameRec  t 
RTS 


iPoLTiter  to  rectangle 


TfieRect  DC         I  2  '  30  , 20  , 1 00  , 1  20  '    iTop,   Jefl,   bottom,  rigtit 
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Notice  that  the  tcordinatif  s  fnr  the  r<?ftaiigle  are  specified  in  top.  left,  bottom,  rigKt 
(TI-BR)  nrder, 

Ti>  ifmae  the  rectangle,  use  EraseRcct: 

PushPtr   TheRecl  ;PoiTiter    Ic  rectangl* 

To  invert  the  piitels  inside  the  rectangle,  me  InvertBcct; 

PushPlr  ThtRect  ;Pairter    io  reclargle 

_l  river  tHec  t 

Tti  filt  the  interior  of  a  rfft'taiigl**  with  the  current  pen  pattern,  use  PaintRcfl: 

PushPtr  TheRcct  tPointer    to  rectangle 

_PaiTitRe{:t 

To  fill  il  with  any  iirhitrdry  patteni,  usf  FillKeel; 

Pu5hPtr  TticRect  iPointer   to  r^€ctongle 

PuahPtr  TtiePetlern  iPointer    to  pattern  definilion 

.FiilRect 

Tlie  pattern  dt-tiiiitioii  defines  an  8  by  8  pixel  grtd,  an  explained  in  the  section  ahove 
called  "Paftemi  and  Colors.  " 

The  fcirrespuitdiiig;  sliapr-driiwjiiE  fnnttions  for  other  shapes  have  suffices  of  Rgn 
(regions}.  Poly  <polygons),  Oval  (uvals}.  RBt-L-l  (round  rectaiifiles),  and  Arc  {arcs). 
The  functions  are  called  in  much  the  same  way  as  the  corresponding  rectangle 
funL'tions,  but  instead  of  piis.hiiig  a  pointer  lo  a  reetansle.  puih  the  foUqwing 
information: 


For  regions,  a  hanclle  to  the  region 

For  ix>lygon5,  a  handle  to  the  polygon  defiDitinn 

For  ovals,  a  pijinter  to  the  imaginary  rectangle  enclosing  the  oval 

For  round  reetanRles,  a  pointer  to  the  imaginary  rectanple  ^nclosinK  the  round 
rectangle,  followed  by  iwo  words  describing  the  width  and  height  of  tlie  ima- 
ginary ova]  inscribed  in  etieh  c-orner 

For  arcs,  a  pointer  to  the  im:isiriar>'  rectangle  enclosing  the  imasjnaiy  oval  of 
which  the  arc  forms  a  part,  followed  by  two  words  describing  tlse  starting^  angle 
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of  the  arc  (in  degrees)  and  the  extent  of  the  art  (ill  dcgreesK  Angles  are  measured 
relative  to  a  vertit^al  axis  moving  up  from  the  center  of  the  oval 

Note  that  the  intprior  of  an  are  is  actually  the  wedpe  bounded  by  the  arc  and  the 
imaginary  lines  from  the  ejids  of  the  iirt:  to  the  center  of  (he  enclosine  oval. 

Polygons 

in  the  previous  section,  we?  came  acrro.5s  a  shape  called  a  polygon.  A  polygon,  as  any 
student  of  gfonielry  can  tell  ycni,  is  an  enelihsed,  multisided  object.  To  define  a 
polygon  with  QuickDraw,  first  open  a  polygon  recurd  by  cdliiiij^  OpenPoly.  US  follows; 

f>HA  ;5pBC<!   far   result  (handle) 

PHA 

_DpeTiPoly 

PopLong  PolyHndl  {Pop  handlt  to  polygon 

The  next  step  is  lo  draw  the  outline  of  the  polyi4<5n  by  iiiakins  a  series  of  calls  to 
LineTo  until  the  entire  outline  has.  been  traversed.  Thfse  lines  are  not  actually 
displayed  oti  the  screttii;  the?  LincTo  parameter!)  are  jusl  stored  in  the  poly^nti 
record.  Finally,  call  ClosePcily  ino  parameters)  to  complete  the  polygon  creation 
process. 

Using  the  polygon  handli*  returned  hy  OpenPnlv,  VOL!  tan  perionn  all  the  Htandard 
QuickDraw  drawing  operations,  such  as  FrameHuly.  PaiiitPoly,  and  FillPnly.  The 
polygon  you  draw  appt'arK  at  the  same  pusitiun  at  which  it  was  defiiH^d,  unless  you 
shift  its  position  with  the  OffsetPoly  function; 

Pu5hLDiig  PoiyHnd.!  ;Polygon  handle 

PaatiWord  #horiE  iHonzgrtal  displacement 

PuahUlord  #vert  ^VertiCdl    d  1  9p  1  acemen t 
_Uf f aelpDly 

Positive  displacements  arc  down  and  to  the  risht. 

When  you  do  not  need  the  pulyj^un  any  uiore,  dispose  of  it  by  calling  KillPoly; 

PushLong    PolyHrdl  iHandle    tc    polyigon  record 

_Ki  1  IPoly 

This  frees  Up  the  memory  spate  QuickDraw  previously  allucated  fur  the  polygon 
re Lord. 
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An  exampU'  af  huw  to  deal  with  polygons  is  given  in  listing  6-6.  This  code  dcfliUL's 
a  pentajion  and  draws  it  un  the  st-reen, 

CREATING  AN  APPLICATION  WITH  WINDOWS 

N«w  that  methcidt;  nf  tTifatin,^  wiiiiiows  iiiitl  drawing  charatters  and  objects  have 
been  (.-overed.  it  is  time  to  put  it  all  together,  Tlie  program  in  listing,  6-7  shows  how 
to  implement  many  of  the  iniporlant  riiiiclioii.'i  thai  have-  hvvn  djsciis.sed  in  this 
chapter,  II  also  diustrates  hnw  k>  deal  with  stmll  toiitrtils  iiml  update  prc«-edures. 

This  pruj;raiii.  tiillfd  TestHeader,  loads  a  readable  text  RIe  into  memon.'  fr«m 
disk  and  lets  you  view  any  part  of  it  using  the  right  and  bottom  scroll  controls  nf  a 
wijidow. 

In  this  program^  tlie  file  is  loi^ded  into  inc:mnr>'  u-sing  several  ProDOS  IB  com- 
maniU  thai  have  not  liicn  wivercd  yet— OPEN.  NEWLINE.  C;e:T_E()F.  HEAD, 
and  CLOSE.  These  commandis  will  bf  disciiss.r;d  iji  chapter  li],  aithouj^h  you  ean 
probably  i^iiess  what  most  of  them  do  already.  The  pnisram  also  uses  an  SFCetFile 
dialog  box  to  request  the  name  of  the  file  tn  be  loaded.  This  dialog  box  will  also  be 
discussed  in  chapter  ID. 

After  loading  a  file  from  disk,  TcxtReadcr  uses  NewWindow  to  create  a  winduw 
with  scrnll  controls  in  its  windnw  frtimc.  it  dues  this  by  settinji  the  rij^lit  and  bottom 
scroll  bjt^  of  the  window  frame  word  in  Ni'wWindoW  s  paranieler  liil.  It  also  sets 
the  bits  for  a  title  har,  yjtnm  box,  and  j^rnw  hoi. 

Scvcra]  other  items  in  the  winduw  parameter  hsl  must  he  set  up  for  any  window 
Lontainini^  scroll  controls.  Firsit,  you  must  specify  the  nundier  ij(  lines  iht^  content 
region  of  the  window  should  stroll  when  the  mouse  is  pressed  in  diflerent  parts  of 
the  Scroll  contrcib  [escept  the  ihumbs},  "I'extReader  is  designed  to  scroll  one  entire 
line  uf  test  if  the  inuuse  iji  pressed  in  tlie  up  or  down  arrow  of  the  right  scroll 
control,  Thus,  a  value  of  9,  the  pixel  height  of  the  system  font  TextReadRr  uses,  is 
stored  in  die  yppropriiite  pcisitiun  in  the  parameter  table.  A  convcniejit  scrollinn 
di_staiice  lor  iiclivity  in  tlie  left  or  right  arrow  nf  the  Imttoin  scroll  hai  h  12  pixels, 
because  tins  is  tiie  niaximuin  width  ul  a  character  in  the  system  fonl- 

Tlie  iitrullinjs:  distance  for  activity  In  the  page-up  or  paEe-down  rpginns  of  the 
fighl  scroll  bar  is  [he  iull  height  of  the  content  regirm,  minus  the  heinht  of  one  line 
(9  pixelsV  The  height  of  one  line  is  subtracted  tn  ensure  that  all  hnes  are  not  scrolled 
off  the  screen — this  makes  it  easier  for  ihe  user  to  l;*;ep  track  of  a  .'^crollin^  operation. 
Similarly,  the  scrolling  distance  lor  the  pagc-k-ft  and  page-right  rcyions  of  the  iioltoin 
scroll  bar  is  set  to  the  width  of  the  s  onteiit  region,  minium  12.  Both  of  these  distances 
are  updated  c^  ery  lime  Task  Master  returns  a  non-null  event  in  case  the  window 
has  been  resized  b>  zooming  or  by  dragging  thi'  grow  box. 

The  next  step  is  to  specify  the  niaximimn  height  and  width,  in  pixels,  of  the  block 
of  text  being  displayed  in  the  window  This  information  is  needed  su  that  the  size 
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fif  the  scnill  t-dntml  thumbs  and  pa^ii:  rtpioiis  t  an  lit-  wilLukted,  Fnr  t-xampir,  (he 
ratkj  (if  thf  Iit-iKliI  f)f"  th*-  tbiiiiili  in  tlu-  righl  Ktnill  Imr  to  the  hciylit  tjf  tht=  t-iilirt- 
scmll  Iw  is  tlif  iaiiif  us  tin-  nitio  d!  hi^ip-ht  of  tlic  Loiiti-iil  rcpioii  lt»  llit-  llt-iflllt 
ol  thr  lloi'll!lll-|lt. 

In  Tc^IRimcUt,  llif  m.iximuni  witllh  is  se  t  to  9fi(>  mn  tlit'  iASSUiJipHim  lhat  no  line 
will  1k'  wiiii,'r  Ht^ii  8(>charj<irrs  ;reinL'nilKT.  tlu'  inLixiniuni  vvicllll  of  a  sin(;l<f  (.'hanitter 
is  12  pi\t'lsl,  The  niiixiiiiiiTn  hviakl  is  st-l  iiiilially  tn  an  arhitr;ir>-  l,()24_  hut  this  is 
chant;t'<l  tinct'  Hu-  file  has  ht  cii  kjatlfil  and  its  h^nln  is  knnvvn,  TcxtRt  adtr  Liikulalfs 
ihf  hi-inht  h\  si.aiuiiii(i  the  InaJcd  file  lor  eiicUur-lint-  LhiirattcTs  (L'arriaEe  returns) 
and  addiiiR  iJ  Ui  ihf  DncSizt'  \arial)le  for  every  nne  it  finds,  An  arbitrary  figure  fif 
20  pisiOs  is  added  to  the  lii-ifjht  to  5;ivf  llie  [Int-iiint-nt  li  ImlUnn  margin 

Anolbi'i  |jaraine!er  you  must  st  l  helort-  callinj;  NL-\v\Vindo«  is  thi'  tme  holdins, 
the  |Tositi<in  within  the  dcjcninLtit  thai  corresponds  tu  the  top  left  Lurnt-r  of  the 
cnntonf  r■t■^;i^ln.  NewWindiivv  ilse-s  this  paramoti^r  to  delertnim-  wht-rt  to  dmw  the 
Ihiimhs  cif  thf  sLnili  bars.  Tt-xtReader  sels  this  pniiitioii  to  11,(1  st>  that  the  top  line 
c}f  the  text  will  appear  at  the  tup  of  the  window  when  the  content  region  is  updated 
fur  the  First  time, 

The  last  SLmlliiifi-nlated  pjriiintteT  that  tnut,t  be  :Stt  is  the  one  Lontaining  the 
address  of  the  stihnniline  that  TaskiMiister  calls  when  the  window  needs  updating. 
EvtTv  serolliu^  operation  forees  a  sertrn  update,  Wause  cver>-  .such  niovenietit 
hritijiJ-  a  new  portion  of  the  doeuinent  into  \iew.  This  subroutine  is  ealled  Wind- 
Update  in  llie  TentReadtT  program  and  is  responsible  for  redrawing  the  content 
region  ol  the  wiiidn« , 

Heibre  TaskMastor  ealls  the  W  indUpdatt-  seieen  updating  submuline,  it  uses 
SetOripiii  to  assign  the  tup  left-hund  comer  of  the  window's  eontent  region  to  the 
[Kisition  within  tin  doeuinent  siiven  b>  the  values  of  the  scroll  footrol,^.  This  meani 
that  tlie  eontent  region  is  tJreLidy  aliiim'd  with  the  active  pdrtiun  oi  the  docimieot. 

The  easiest  way  to  update  thf  content  region  is  simph  to  redraw  the  entire 
dofUineilt;  because  drLiwing  is  dipped  to  the  eontent  rt  jiiim,  you  will  not  mess  up 
other  areas  of  the  sereeii.  This  is  not  a  sLilislattory  method  for  large  documents, 
however,  because  it  is  very  slow — after  uJl.  yoii  must  go  through  the  charade  of 
redrawing  portinns  of  the  dix  iiuK^nl  that  dn  not  iictiially  appear  iu  the  wnndow, 

A  much  faster  alternative,  the  one  osed  hy  TestReader.  is  to  redraw  ooly  that 
portion  of  the  document  appearing  in  the  content  region.  To  locate  the  first  line 
that  will  appear  iii  the  eoiitent  region.  TextHeadt  r  first  /_<?roes  a  tounter.  then  adds 
9  {the  line  height!  to  the  countpr  for  each  eiid-of-line  eharaeter  (carriage  return)  it 
finds  whiEe  scanning  through  the  doi-iiinenL  from  the  bet^inning.  When  the  counter 
becomes  greater  than  the  vertical  position  of  tlw  top  oi  the  content  rrgiiin  (stored 
at  PortPcct  +  tupl.  the  search  is  over.  Eai^h  line  in  the  doeujuent  is  then  drawn  [with 
DrawTcxC!  untd  the  pen  ixisilion  is  nne  clear  line  beltisv  the  bottom  of  the  content 
region-  iCarria[;e  return  codes  are  handled  by  calhn^  CKLF  to  move  the  invisible 
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drawing  p^^n  to  left  sick-  tif  eIic  next  line.)  TeslKcader  does  ni>t  bother  ta  do 
runst  chi  ekinc;  on  thf  aides,  aJtliuugh  ym  Lould  add  tiodv  ia  do  this  ta  make  updates 
happen  a  bit  faster 

TiskM.ister  <^'alls  the  update  handler  with  a  JSL  mstnicticin.  so  the  huiidbr  ends 
with  an  RTL  instruttifm.  Do  nut  end  with  an  RTS  instruttioTi  as  you  wonld  ii  the 
routine  was  Cidied  witK  JSR.  Another  tip  on  writing  an  updak=  handler  relates  la 
the  direct  pape;  the  active  dircLl  pagr  when  TaskMastcr  calls  the  update  handler  is 
not  the  direct  page  tht  apphtalion  n^c^.  If  y  ou  most  act'css  data  in  the  applit-ation  s 
direct  page,  perhaps  to  use  pointers  you  havp  previnnsly  set  up  in  direct  page, 
switch  to  "the  direct  pa^e  first  The  WindUpdatr-  aobrouHne  does  this  so  that  it  can 
acL-ess  thr  direct  pa^e  pointer  to  thv  text  bfoc-k. 

Once  TestHeader  defines  the  window  aud  loa.dK  ihp  text  fik-.  it  enters  a  short 
TaskMa^ter  event  loop.  Because  TaskMnster  autumaliciilly  takes  cjire  of  all  mouse- 
down events  in  tht'  stroll  hars  and  hLindles  .Ul  vipdiitr  events,  the  application  does 
not  havF  tn  do  anything  special  to  support  serulling, 
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Table  Rd-h  The 

Major  Functions  in  the  Oi''ckD 

raw  11  Tool  Set  (SCH] 

Function 

S  fact 

DescriptUin  of 

Pttnction  Name 

?J  limber 

Paraiiieters 

FaramL'tcT' 

CharWiddi 

result  (W) 

Width  nf  L'haracter  in  pixels 

Char  (VV) 

The  chiiraeter 

Close  Poly 

SC2 

[no  parameters] 

CStringWidth 

SAA 

result  (W^ 

Width  of  string  in  pwels 

TheCString  |L) 

Ptr  to  C-style  text  string 

Draw-Char 

^A4 

Char  IW) 

ASCII  code  for  eharacter 

DrawCString 

i5A6 

TheCStrinE(L) 

Ptr  to  C-style  text  strinp; 

DrawString 

$A5 

TheStrine  {L} 

Ptr  to  text  string 

DrawText 

SAT 

TheTesl  (L) 

Ptr  lo  start  of  text 

Count  {WJ 

Number  of  charaolers  to  draw 

EraseArc 

S64 

[lectan^le  (L) 

Ptr  to  rectangle 

StartAngle  (W) 

Starting  an^le 

AreAngle  (W) 

Extent  of  angle 

EraseOval 

S5A 

Rectangle  (L) 

Ftr  to  rectangle 
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Function  Name 

Function 

Stack 

Funntteters 

Description  of 

ErasePoly 

«B£ 

PolyHnd]  (L) 

Handle  to  pulyson 

EraseRect 

$55 

Reclangb  (L) 

Ptr  to  rectaiigte 

Erase  Rgn 

$7B 

RgnHndl  (L) 

Handle  to  region 

EraseRRect 

$3F 

Kettan^le  (L) 

Ptr  to  rectangle 

OvalWidth  fW) 

Width  of  corner  oval 

OvalHeifiht  (W) 

Height  of  comer  oval 

FilUiL- 

Rectangle  (L) 

Ptr  tn  arc's  rectangle 

SlartAngle  (W) 

Starting  anft]c 

ArcAngle  (W) 

Extent  of  angle 

PatrcniPtr  (LI 

F(r  to  fill  pattern 

FillOval 

$sc 

Rectangle  (L) 

Ptr  to  oval's  rectangle 

PaltemPtr  (L) 

Ptr  to  fill  pattern 

FillFoly 

SCO 

PuSyHndl  (L) 

Handle  to  polygon 

PatternPtr  fL] 

Ptr  to  jill  pattern 

FOlRect 

»57 

RettangEe  (L) 

Ptr  to  rectangle 

PalltmPlr  (L) 

Ptr  to  the  fill  pattern 

FiMgn 

S7D 

Rgnllndl  (L) 

Handle  to.  regioTi 

FattemPtr  [Lf 

Ptr  to  the  fill  pattern 

FiDRRect 

mi 

Rectangle  (L) 

Ptr  to  rrect's  rectangle 

OvalWidth  (W) 

Width  of  comer  oval 

Oval  Height  (W) 

Height  of  CMiraef  oval 

PattemPtr  (L) 

Ptr  to  fill  pattern 

FraraieArc 

362 

Rectangle  (L) 

Ptr  tc}  rectangle 

StartAngle  (W) 

Starting  anf^le 

ArcAngle  (W) 

Extent  of  anffls 

FrameOval 

$.58 

Rectangle  (L) 

Ptr  to  rectangle 

FmmcPoly 

SBC 

PolyHndl  (L) 

Handle  to  polygon 
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Function  Name 

U  lltSfttiHi 
1   14  tmt.  t 

umber 

PurtniitHers 

T){;s€ ription  of 
Parameter 

FraineKet'l 

S53 

Rtetangle  (L) 

Ptr  to  rectangle 

FrameRgn 

S79 

RfTiiHnd]  (L) 

Handle  to  region 

FrameRRect 

$5E 

Rectangle  fL) 

Ptr  to  rectangle 

OvalWldth  (W) 

Widlh  nf  ramer  oval 

OvalHeight  (WJ 

Height  of  Mmer  oval 

GetBackColor 

*A3 

result  (W) 

Background  culor  number 

GetBackPat 

S35 

PattcmPtr  {L) 

Ptr  tn  the  background  pattern 

GctCulorEntry 

$11 

result  (W) 

Cok^r  entry  v^ue 

TableNum  (W) 

Color  table  number 

Entn-^Num  (W) 

Color  number 

GetColorTable 

$0F 

TableNum  [W) 

Color  table  number 

ColorTblPtr  (L) 

Ptr  to  space  for  color  table 

GelFontliilo 

FJRcctPtr  (L) 

Ptr  to  font  info  record 

GelForeColor 

result  {W) 

Foreground  ciilnr  nunsber 

Get  Pen 

PointPtr  (L) 

Ptr  In  space  for  poiai  resuk 

Gel  Pen  Mask 

MaskPtr  (L) 

Ptr  to  space  for  pen  mask 

GcrtPcnMode 

S2F 

result  fW) 

Current  pen  jnode 

GetPenPat 

S31 

PatttmPtr  (L) 

Ptr  to  current  pen  pattern 

CetPenSize 

$2D 

PointPtr  (L) 

Ptr  tn  width/beight  result 

CetPen  State 

$SB 

PenStatePtr  (L) 

Ptr  to  space  for  PS  record 

Get  Fori 

SIC 

result  (L) 

Ptr  to  current  CrafPort 

Get  Port  Rect 

h520 

RectPtr  (L) 

Ptr  to  space  for  rect  result 

GelSCB 

S13 

result  (W) 

Scan  line  control  byte 

Scan  Line  (W) 

Scanline  number 

GetTextFace 

$9B 

result  (W) 

Current  textface  word 

CetTextMo:!e 

S9D 

result  (Wl 

Current  text  drawing  mode 

CIobalTo  Local 

$85 

PointPfr  (L) 

Ptr  to  point  to  convert 
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Functiun  Name 

Flinrtion 

Slack 

ParumnlCrs 

Faramt'tcr 

InitCulurTable 

SOD 

ColnrlljlPtr  (L) 

Ptr  to  space  ifni"  L-iiliir  table 

InvertArc 

$65 

Rectangle  [Lf 

Ptr  to  arc's  rectangle 

SfartAnfjIe  (Wl 

Starting  angle 

Arc-Angle  (W) 

Extent  (jf  angle 

IiivertOval 

$5fl 

Rectangle  (L) 

I'tr  to  oval  fi  rectangle 

InvertPoIy 

SBF 

PnlyHndl  (L) 

Handle  lo  pnlygmi 

InvertRect 

$56 

Rectangle  (L) 

Ptr  tci  rectangle 

InvertRgo 

$7C 

RgnHndl  [LJ 

Handle  to  region 

InvertRReLt 

$60 

Rectangle-  (L) 

ptr  tn  rreet's  rectangle 

OviilWidlh  (W) 

Width  of  comer  oval 

OvalHci^ht  (W) 

Height  of  corner  oval 

KillPoly 

|C3 

Filly  Hnd] 

Handle  to  polygon 

Une 

S3D 

hOfiset  (W) 

Horizontal  offset 

vOffset  (W) 

Vertical  offset 

LineTo 

$3C 

hPos  (W) 

Horizontal  positiOQ 

vPos  (W) 

Vertical  position 

LocalToGlabid 

$84 

FointPtr  {L) 

Ptr  to  point  to  convert 

Move 

DispX  (W) 

Horizontal  displacement 

DispY  (W) 

Vertical  displacement 

MoveTo 

IS3B 

HnnzPos  (W) 

Horizontal  position 

VertPos  ^WJ 

Vertical  position 

Offset  Poly 

»C4 

F<3U  Hnt!l  (L) 

Handle  to  polygon 

hOffsel  (Wl 

Horizontal  displacement 

vOHiel  (W) 

Vertical  cSisplacement 

OpenPolv 

$C1 

result  (U 

Handle  to  polygon 
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Fhik'Hhh  Name 

S'ltmhfy 

Stack 

Fii/'ujnstsrs 

Dexcriptioi\  of 

r  HI'  ti  ificirr/ 

PaintArc 

S63 

Rectangle  (L) 

Ptr  to  rectangle 

StartAngle  (W) 

Starting  angl^ 

ArtAnglp  (W) 

Extent  of  angle 

PaintOvai 

$59 

Hcctanjslf  ;L) 

Ptr  to  rcctan)?ie 

PaintPoIy 

$BD 

PolvHndl  (L) 

Handle  to  pnlygon 

PaintKwt 

S.54 

HeclaiigEe  (LJ 

Ptr  to  rectangle 

87A 

RfinHndl  (L) 

Handle  io  region 

Paint  RReel 

$5E 

Reclan§!le  (L) 

PLr  lo  rectiin^le 

OvaiWidth  (W) 

Width  of  comer  oval 

OvalHeight  {W) 

Height  of  comer  oval 

PcnNdTITliU 

|>13H 

QDShutDuwn 

$03 

[no  parametprsj 

QDStartup 

$02 

CPAddr  (W) 

Address  of  3  pages  in  bank  0 

MasterSCB  (W) 

S8000  =  640/SOOOO  =  320 

Sizef  oi  largest  pixfl  map 

UserlD  (W) 

ID  tag  for  inemnry'  alloc-atioii 

SetAllSCUs 

$14 

NewSCD  (W) 

New  SCB  value  for  all  lines 

SctBiK'kCukjr 

ColorNiiiii  (W) 

Background  color  number 

SetBackPat 

$34 

Pattemflr  [L) 

Ptr  tij  new  background 

piittern 

SetCo]oTEiitr>' 

sio 

TaMfNiimlit-r  IW} 

Cnlor  table  number  (0-15) 

Entrj'Nuiiiber 

Color  number  in  table  ((}-15) 

tW) 

NcwCdkir  (W) 

Nc\v  fi'liir  value 

SetCnlnrTiililf 

TableNumber  (W) 

Color  tablt  nuniWr  (0-15) 

CnlorTblPtr  (L) 

Ptr  tn  nevi  L'olor  table 

2(4    Wimliiws  imd  Crajiliicx 


Punctinn  iVomi? 

Siimber 

Purameter 

SetFoTitFlags 

FotitFlas  (W) 

New  font  flags 

SetForeColor 

SAO 

ColorNum  (W) 

Foreground  culor  number 

SetOrigin 

$23 

xOH^^in  (W) 

X  c^ourd  of  uppCT-left  corner 

yOrigin  (W) 

Y  uourd  iif  upptir-left  comer 

SetPi-nMask 

S32 

MaskPtr  (U 

Ftr  to  the  new  pen  mask 

SetPeiiMode 

S2E 

PenMddc  (W) 

New  pen  mode 

SetPenPat 

$30 

FatttrnFtr  (L) 

Ftr  to  new  peci  pattern 

SetPenSize 

nc 

Peii Width  (W) 

WidUi  of  pen  in  pixels 

PenHeighl  (W) 

Heij^ht  of  pen  in  pixels 

SetPenStntc 

PeiiStatePtr  (L) 

Ptr  to  pen  state  record 

SelPort 

SIB 

PortPtr  [L) 

Ftr  to  new  GrafPorl 

SetPortRect 

SIF 

Re-dangle  (L) 

Plr  to  new  port  rec^tansle 

SeCSCB 

ScanLjiie  (W) 

Scan  line  number  (0-199) 

NewSCB  (Wl 

New  SCB  value 

Sets  olid  BaukPiit 

m 

ColorNuiii  [W] 

Color  #  of  bat^lcfrround 

pattern 

SetSolidPenPat 

$37 

ColorNum  [W] 

Color  #  ftir  pen  pattcni 

SetTextFace 

.?9A 

TeKlFacf  (W} 

New  tcxtfscc  word 

SetTextMode 

$9C 

TexlModt-  (W) 

New  lext  drawing  mode 

SolidPattern 

$39 

CobrNum  (W) 

Color  number 

PatternPtr  (LJ 

Pointer  to  pattern  for  color 

StruifiWidth 

SAB 

result  [W) 

Width  ul  string  in  pixels 

TheSlring  (L) 

Ptr  to  text  string; 
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Function  Slack 
Function  Nome      Number  Parameters 


Description  of 
Parameter 


Width  of  text  in  [pixels 
Plr  tn  start  of  text 
Niimbitfr  of  characters 

Table  R6-2;     QuirkPraw  II  Error  Codes  

S0401  QuickDraw  11  has  atrpady  hccn  initiahzed. 

$0403  guicliDraw  [I  haff  not  hfpn  initiaJizcd. 

$0410  SLreen  inciTinrv'  has  l>e£.'n  reserved. 

$0411  Thtf  rectangle  specified  in  invalid. 

$0420  The  pixel  chuiikines^  is  not  equal. 

$0430  The  reRiim  is  already  open, 

$0431  The  region  is  not  open, 

$0432  The  region  has  overflowed. 

$0433  The  region  is  Cull. 

$0440  The  polygon  is  already  open. 

$0441  The  polygon  is  not  open. 

$0442  The  polygon  is  too  big. 

$0450  Bad  color  tabic  mnnber 

$0451  Bad  color  nninlM-r. 

$0452  Gad  Sean  line  numlier. 


TextWidth  SAB  result  (W) 

TheTest  (L) 
Count  (W) 


Table  R6— 3:    The  Major  Funt'tioii>;  in  fhe  Window  Manaj^er  Tod!  Set  (SOE) 


ftincfiorf 

Stack 

Description  of 

Function  Name 

Number 

Parait\eteri- 

Parciuieter 

BeRin  Update 

$IE 

ThcWindow  (L) 

Ptr  to  window  record 

Close  Window 

$0B 

TheWindow  (L) 

Ptr  to  window  record 

DragWindow 

$1A 

Grid  (W) 

Drag  resolution  {0  =  delault) 

StartX  (W) 

Starting  X  coord  [global) 

StarlY  (W) 

Starting  Y  coord  [global) 

Grace  {W) 

Grace  distance  around  bounds 

BoundsRect  (L) 

Ptr  to  cursor  boundary  rect 

TheWindow  (L) 

Ptr  to  window  record 
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Function  Name 


Function 
Number 


Stack 

Parameters 


Description  of 
Parameter 


EndUpdate 
Find  Window 


$1F 
$17 


FrontWindow  SI5 

GetContentDraw  $48 

GetConleiitOrigin  $3E 

GelDataSize  $40 

GetDeiProc  $31 

GetFrameColor  $10 


CetFullRecC 


$37 


GetlnfbDraw  UA 


GetlnfuBefCon  $35 


GetMaxGrow  M2 


TheWindow  (L) 
result  (W) 
Which  Window  (L) 
PoLntX  (W) 
PointY  [W) 
result  (L) 
result  (L) 
The  Window  [U 
result  (W) 
result  (W) 
The  Window  [L] 
result  (W) 
result  (W) 
TheWindow  (L) 
result  (L) 
TheWindow  (L) 
result  (L) 
TheWindow  (L) 
result  (L) 
TheWindow  (L) 
result  (L) 
ThrWimdow  (L) 
result  (L) 
TheWindow  (L) 
result  (W) 
result  (W) 
TheWindow  (L) 


Ptr  to  window  record 
Ixjcation  code  for  mousc-dowti 
Ptr  to  space  for  window  ptr 
X  coord  to  check  (global) 

Y  ciiord  to  check  (global) 
Ptr  to  windt}w  recnrcl 
Ptr  to  update  subroutine 
Ptr  to  window  record 

X  coordinate  of  oii^n 

Y  coordinate  of  origin 
Ptr  to  window  record 
Data  width 

Data  height 
Ptr  to  window  record 
Ptr  to  window  def.  subr. 
Ptr  to  window  record 
Ptr  to  color  table 
Ptr  to  window  record 

Ptr  to  window  record 
Ptr  to  infobar  drawing  subr- 
Ptr  to  window  record 
RdCon  for  infobar  drawing 
Ptr  to  window  record 
Mfwiiiium  window  width 
Maximum  window  height 
Ptr  to  window  record 
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Function  Nairn: 

Functiirn 

Number 

Pctrumelern 

Devcriptioti  oj 
Parameter 

SAC: 

reiyiilt  (W) 

HoriKonlal  distance  (p-igc) 

 f\\>\ 

Vertical  distance  (page! 

1  n«?  vV  tUdOW  [IjJ 

V\t  to  wiiidow  record 

Hnriznntiil  distuncc  (line) 

result  (W) 

Vertical  distance  (line) 

ihfWindow  (Lj 

Ptr  to  window  record 

ijCl  Wrrarne 

resiiJt  {W) 

Window  frame  Hit  vector 

J  hrWinoow  (L| 

Ptr  l[)  windiiw  remird 

ri;!.ult  {I-,} 

Referent*  cunstant 

J  nevvintiow 

Ptr  tfi  window  rtt'ord 

LicrW  1  itle 

result  tLj 

Ptr  In  title  string 

L  lie Wiiiut>w  (Li) 

Ptr  to  window  record 

GrowWindnw 

c  T  n 

result  (W) 

New  height 

result  (Wj 

New  widtl) 

_vi  m  wiutn  \  W) 

Minimum  width  of  coiifent 

-McLKWidrh  ( VVJ 

Maxim  um  width  of  content 

Startiiig  X  coord  [global) 

Stan  I  \Vv ) 

Stia.rtl]ig  Y  coord  (globiil) 

ThfWindow  (L) 

Ptr  to  window  ret-flrd 

HideWindiJw 

$12 

TheWindow  (L) 

Ptr  to  window  record 

MuVe  Window 

New\.  (VV) 

X  coord  of  upper-left  comer 

NewY  (VVl 

Y  coord  of  upper-left  comer 

TkeWindow  (L) 

Ptr  to  window  record 

Nt^wWiadow 

soy 

result  (L) 

Ptr  to  window  record 

ParamLlst  (L) 

Pfr  to  window  paraml^^^el'  table 

RefreshDesktop 

ClobRect  (L) 

Ptr  to  redraw  rectanj;le 

Select  Window 

Sll 

TheWindow  fU 

Ptr  to  window  record 
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Function  Xtime 

h'unciioii 
\'tiinhi'r 

Paraiiieiers 

Dt^ficriplioii  of 
Partiiiu'tcf 

St"  tCtinl  ent  D  raw 

$49 

ContDraw  |L) 

Window  update  prtn?edure 

TlieWiiidow  (L} 

Ptr  tu  window  rcccird 

bctCantentOrigiii 

$3F 

xOrigin  (W] 

X  coordinate  of  uriffin 

yOrigin  fW) 

Y  coordinate  of  origin 

TlieWindow  (L) 

PlT  lo  windnw  record 

St'tDiitaSizt' 

dataWkkh  (W) 

Data  width 

datuHcipht  (W) 

Data  hri^lit 

TheWinciow  [L) 

Ptr  to  window  record 

SelDefl^rnc 

DcfPmc  (L) 

Window  dt-Riiiiion  proecdL 

ThrWiiidow  (L) 

Ptr  to  window  record 

SelFraiiieColnr 

St)F 

FrCnInrTljl  (L! 

Ptr  to  new  L-olor  tabic 

ThcWindow  (L) 

Ptr  to  window  record 

SetFullRccI 

S38 

FullKect  (L) 

Ptr  Id  zoom  rectangle 

Tlii^Window  (L) 

Ptr  to  window  record 

SptliifnDcavi' 

$1G 

InfuDraw  (L) 

Information  bar  procedure 

TliLAVindow  (L) 

Ptr  to  window  record 

St'tlnfoReCCon 

S3fi 

liilijKt'JCoii  (L) 

Infobar  reference  constant 

HieWindrnv  (L) 

Ptr  to  window  record 

SetMaxGrow 

iiiaxWidtiT  (Wi 

Maximnini  window  width 

iiiiixHeight  (W) 

Miiximum  window  heiplit 

TheWimlow  (LI 

Ptr  to  window  record 

SetPage 

$47 

hPasJe  (W) 

Horizontal  distance  ipa^c) 

Vertical  distance  (page) 

ThrWinduw  (L) 

Ptr  to  wiodow  rccorri 

SelScroll 

$45 

hScrnll  (W) 

HoriiOnlal  distance  (line) 

vSltoII  [W) 

Vertical  distance  (line) 

TlieWindow  (L) 

Ptr  to  window  record 
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Function 

Stack 

Parameters 

Description  of 
Parariieler 

SetSvi  Window 

TheWindow  (U 

Ptr  to  systEm  window 

SetWFraine 

WFrainc  (W) 

Windciw  frame  bit  vector 

ThpWindow  (L) 

Ptr  to  window  record 

SetWRefCon 

WRcfCoii  (L) 

New  reference  ctmstant 

ThtAVindow  (L) 

Ptr  lo  window  record 

SeCWritle 

TitlePtr  (L) 

Ptr  to  new  title  string 

TheWindow  {L) 

Ptr  to  window  rerord 

ShowWindow 

S13 

TheWiiidow  (L) 

Ptr  to  window  record 

Sizt^VVintlnw 

SIC 

NewWidth  (W) 

New  width  of  window 

NewHt^ght  (W) 

New  height  of  window 

TheWindow  (L) 

Ptr  to  window  record 

Start  Drawing 

S4D 

'I  hcWindow  {L) 

Ptr  to  window  record 

TaskMaster 

$1D 

result  (W) 

Event  code 

EventMask  (W) 

Event  mask 

TaskRtLmd  { L) 

Ptr  to  task  record 

TraclcGoAway 

SIS 

result  (W) 

Boolean:  was  goaway  selected? 

StartX  (W) 

X  coordinate  (global) 

StarlV  (W) 

Y  Loordinate  (global) 

TheWindow  (L) 

Ptr  to  window  record 

Trac-kZoom 

$26 

result  (W) 

Boolean:  was  zoom  selected? 

StartX  (W) 

X  ^ordinate  (global) 

StartY  (W) 

Y  coordinate  (global] 

TheWindow  (L) 

Ptr  to  window  record 
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Ftinetion     Stack  Descrijiticm  of 

Functian  Narne       Number     ParariietiTi-   Pararneter 

WindShutDown      S03  [no  parameterji) 

WindStarlup  $02  Usi-rlO  (W)  ID  tajr  for  memory  {JlcKation 

ZoomWindow         $27  TheWindow  (L)       Ptr  tn  window  reciird 

Table  R6-4:      Window  Maiiagtjr  Error  Codes 

SOEOl       The  first  word  in  the  NewWmdow  parameter  list  is  not  the  correct 
table  size. 

S0EO2      The  window  record  could  not  be  allocated. 

SOE03       Bits  J4-3.1  in  the  TaskMiiik  field  of  the  task  record  are  not  zero. 


Table  R6-^!     Useful  Functions  in  the  Ftmt  Manager  Tool  Set  ($1B) 


Fuitction  Name 

Function 
Number 

Stack 

Parameters 

Description  of 
Parameter 

ChtiuseFont 

$16 

result  (L) 

ID  for  selected  font 

currcntlD  (L) 

ID  of  current  font 

famSpecs  (W) 

Family  spetifieatiun 

Install  Font 

$0E 

desircdlD  (L) 

Desired  font  ID 

scalcword  (W) 

Scaling  fairtor 

FM  Shutdown 

$03 

[no  parameterfij 

FMStttTtiip 

$02 

SvsFontNatne 

Ptr  to  system  font  name 

(LI 

UserlD  (W) 

ID  tag  for  memory  allocation 

DPAddr  (W) 

Fotnter  to  1  pa^e  in  bank  0 
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Function       Stack  Description  of 

Function  Name       Number  Parameters  Paratiieier 

LoadSysFont  $n  [no  parameters] 

SetPurgeStat  $0F  fontID  {L)  ID  for  font  to  purge 

purgeStat  [W)  Purge  status  word 


Table  R6-6:      Font  Manager  Error  Codes 

$1B01 

Thp  Font  Manager  h-is  aJready  been  started  up. 

$1603 

The  Font  Manager  is  not  aetive. 

*1B04 

The  font  family  was  not  found. 

$1B05 

The  font  was  not  found. 

$IB06 

The  font  is  not  in  ineniory. 

?IB07 

The  system  font  cannot  be  made  purgeable, 

S1B08 

lllegi]  Family  number, 

SIB09 

Illegal  size. 

SI  BOA 

rilegal  najTie  lenjjth. 

£1B0B 

FixFontMenu        never  been  called. 
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LijtlTlg  6—1;      How  tn  ('rr'atc  ^ind  Display  u  Wmdinv 


CeflneUind  STflfiT 


PHfl 

PushP  tr     TheW i ndow 
_NeuiLJ  1  ndaw 
PopLong  UindowPtr 

RTS 


;Spacs  for  result 
;Pointer  to  wirdow  record 
;Sa^e  pointer   to  wlndouj  record 


i  Uindow  parameters: 


TheUl ndcw 


WlndEnd 


DC 

1  £ lUtndEnd-TheWl ndow* 

Size  of  table 

DC 

1  'SnOI  1  1  01101001  D1  ' 

windcw  frame  lype 

DC 

H'TheTitU' 

Pointer    to   windoM  trtle 

DC 

i4'0' 

ref con 

DC 

]  '■10,'!. 182, 608' 

iQg-m  rffc  tangle 

DC 

color   table   (D  -  dEfauit  ) 

DC 

1  'O.D* 

document  offset 

DC 

['1024,960' 

h£i ght , wid t h  of  date  area 

DC 

I  'fl,C' 

hejghtiWidth  max  window 

DC 

r '9,1 2' 

vert,  hariz   line  movement 

DC 

[  'Hfl  ,592' 

vert,   horii  page  movement 

DC 

!1'0  ' 

info  bar  refcon 

DC 

info    bar    he  i  gti  t 

DC 

I4'0' 

frafftt  defproc   (0  =  standa 

DC 

14 'Do  rnfoBar ' 

info  bar  defproc 

DC 

[4'UindUpddte' 

cOTitefil  d*fpi*oc 

DC 

P40,4  ,162, GOB' 

Content  region  rectangle 

DC 

14  '  -5  1 

fll    the  -front 

DC 

14'0' 

Storage  (use  MM) 

ThcTltle 


DC 


II'A        Ulndow'      lUindow  tltli 


WlndowPtr  DS 


iPcinter   to  window 


END 


TBstMasler  calls   this  routine  whenever  an  update 
event    occurs.    It    ta    reiponsible  for    redrawing  the 
ccntenta  of   the  window. 


L 
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WindUpdate  START 


;   Make  thp  data  bank   ^'qual    the   code  h^r\i  ygu 
;   can  u^e  ^b^olute  addres^iTi^: 

PHB 

PHK 

PLB  ;datd  bank   "  code  bark 

;    lirsert  window  drawing  code  here] 
PLB 

RTL  ;Do  not   use  RTS! ! 

EHD 

Taatflasler   C3II5   thia   routine  when    il   reeds  to 
draw  the   interior   of   the   Information  bar, 

See  entplarat  iHj  n  in   listtrg  6-2. 
Dol nfoBar  START 

;    [insert  drawing  code  here] 

;   Remove   12  bytes  of    input   parameters  from  the  stack: 

LDfl  2,S  ;Mtiv»?    return  .address 

STA  1 4 , 5  i  up  by  three   long  word^ 

LDS  1,5 
STR  13,S 

CLC  ;Raise  stack  poir>ter  by 

TSC  ithrcelsngwords. 

ADC  '12 

ICS 

RTL 

LHD 


Listing  6—2:     A  Pfuotdure  fur  Drnwinfj  an  Infornutiuii  Bar 

i   This   15  an  information  bar  draMring  procedure.    !1  centers  a 
!    text    5tring    pointed    to    by    the    info  bar    refconi    in    the  bar. 

;    TaakMaster  calls    InfoProc  by  pushing   three   loiig  wnrd^  an  the 

i    5tacl    (pointer    to    infnhar    rertangle,    the    irformation  bar  refcon, 

;  and  a  pointer   to  Ihe  window  r&cord),    then  perfprmtng  a  J5L ■ 
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!   Cn  CKlt,    thEsc  pa  rame lers  must  be  removed  by  movLng  the 
i   retur-n  addreas    [and  stacb    pointsrl    up  by  12  by  tea, 

;   Mole:    top,    left,   bDltom,    right  are  defined    in  Sterdard-Asm. 

InfoPfoc  STflfiT 


;  The^iP  are  the  direct  page  addresses  after  alLgning  the  new 
;  direct   page  with  the  atacii: 


Cld_DP 

EQU 

JO  1 

iDld  direct  pega 

nidloB 

EQU 

Old^DP'l 

iDld  data  bank 

Getiirriflddr 

EGU 

0 ld_DB*  2 

;JSL   return  address 

!fl_Wi.ndPt  r 

EQU 

Relurriflddr»3 

;  Po  1  nt  er   to  windou^ 

i  B^Ref  Con 

EQU 

]H_WiTidPlrt4 

;Geferencie    constant    (siring  pointer 

IB.RectPt  r 

EQU 

jPolnter   to  infobar  rectangle 

PHD 

;Sau&    direct  page 

PMB 

;5ay/e  data  banl:  regiater 

PHK 

;3et   d.ata  banl       code  barli:   ao  we 

PLB 

;   can  use  absolute  addresslnq 

TSC 

TCD 

',  nlign    Tieurf  o.p-    uiilh  ^taci^ 

LDV 

'left 

LDfl 

[ £a_RectPt  r] , Y 

;Get   left  edge 

STfl 

1  B_Tenip 

LD¥ 

*r 1 gh  t 

LDfl 

t IB.RectPtr]  ,V 

;&et    right  edge 

SEC 

SBC 

i  B_TEmp 

;Caiculate  width  of  rectangle 

PHfl 

PHfl 

;Goom  for  result 

DFig    1  B_&ef  Ct>n 

;Pq inter    to   [ext  string 

_StriFigWidth 

PLfl 

;Thi5   15   the  wtdth  of  the  text 

5Tfl 

LB_TeJ33p 

PLA 

;Ge[   width  of  rectangle 

CMP 

IB.Temp 

iWider   than  texf 

BCS 

&e  t  Ma  f  g  i  n 

; Ye3 ,    Sd  branch 

LDA 

;Fly5h  (uith   left  aide 

BRA 

t  Ma  rg  1  ti  1 
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SEC 

SBC 

]B_TErap 

LSR 

A 

ETfi 

lB_Temp 

LDV 

'left 

LDA 

t  t0_Rec tPtrS  .Y 

ADC 

IB_Temp 

PHfl 

LDV 

'b'^t  tom 

LDA 

[IB.RectPlrl.Y 

SEC 

SBC 

PHA 

PushLang  IB.RefCon 

PLB 
PLD 


;Calculate  i-tmaining  apace  in  rect 
[Divide  by  2  t<j  gel    left  ruargin 


lAdd  marglTi  to  left   edge  poaition 

;)t-c;aordindt<?  for  Mo  veto 

jOet   bottom  edge 

descenders  J 

; y -coordi ng te  for  McweTa 

;Position  the  drawing  pen 

{Push  refcor  pointer 

[Draw  airing  poLfited   to  by  refcon 

[Restore  data  bark  register 
;Re5tor>fi  direct  page 


;  Remove  parameters  from  atack  before   leaving.   This  i5  done 
;   by  mov/ing    the  3-byte  return  flddre55,   and   the  stack  pointer, 
i    up  by  the  siie  of    the  parameters,    then  ending  with  RTL. 

iMowe  return  address 
;  up  by  three   long  worda 


iRaiae  stact  pointer  by 
;    Idree    l^)ng  words. 


I  B_Temp 


LDA 

8.B 

STfl 

14, S 

LDfl 

1  .5 

STfl 

13,5 

OLC 

TSC 

AQC 

TCS 

RTL 

D5 

£ND 

;(caUed  with  JSL) 


Listing  6-3:     HowTu  Define  an  STR  Macro 
riACftO 


Alab        STR  Jtext 

4lab         DC  1 1  '  L  :  I  text ' 

DC  C'Heittr' 

MEND 


;  L  eng  t  h  byte 
[fiSCI I  characters 
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Listing  6-4:     Using;  Striit^Width  To  C:t'ntef  a  Line  of  Text 


;   Enter    Ihi^   subroiitine  with  a    line  number    in  V. 

i   The  pointer    to   the    text    strjng  must   be    in  fi    [hiqh)   and    >!  (iow). 


left 

right 


GEQU 
CEQU 


Ctnterlt  STflftT 

STV  LinePoa 

jCslculate  Width  string: 

PHA 
PHft 

PHK 

_5lringWidth 
PopUorct  TextUidth 

;CBLculatc  width  of  content  region: 

PushPlr  PortRect 
GetPcrtRect 


;5awe  vertical 


; spsce  for  rE^ui I 
;pu!sh  pointer  [high) 
;push  pointer    [ low) 


iCet  conlent  rectangle 


sec 

SBC 


PortKectTight  ;Right  ^ide  minus 
PortRect'le^t  ;    the   left,  aide. 


sLeft  margin    15   1  /  2  »  ( Ul  i  ndo-«UI  i  dth-TextUi  d  t  h  )   from  left   of  PortHect: 

;Dlwidc  by  2 


SHE 
LSR 


TexlWidth 


CLC 
ADC 


PortRect' left 


L 1  nePos 


PHA 

Pu^hWurd  LinePos 
_MaweTo 

PuahPlr  TheTesil 

_DrawSt  r 1 

STB 

D5  2 


;ftdd  ta   left  5idE 

jHarizontial  position 
; y^r  1 1 ca J  position 


iDraw  the  string 
jUertLcol    line  position 
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iCantent  rectangle 


PortRect  DS  B 
TextUidlh     DS  2 

END 

Listing  6-Si    A  Subroutine  for  Displaying  Text  iiL  All  Sixteen  Colors 

Use  this  subroutine   m  3£OxS00  mode  so  that  you  see  all 
16  colors.    [Do   this  by  ^f^ttlhg  ^^idMode  to    tOO  and 
KnaiClamp   lo    320   in  StaTidar  d  .  P  am  .  ) 

TsxtCalor  START 

PushWord  '3 
LDA  »\6 
STfl  VertPoa 
PHfi 

_McveTo  ■,  Pa5)tjc3TioFifirat  line 

;    Ju5t    for   fur.   draw  the   text    ir\  boldface: 

PushWord  /SQQDOOOOl  ^Set   the  bold  bit 

.SetTextFace 


LDX 

ColorText  PHX 


«0 


PHX 

^SetForeColor 

PushPlr  ThcTeitt 
_DrawStr  ing, 


;5tBrt  with  color  "0 

;Set  foreground  color 
; Pr 1 n  t    the  test 


;ri[3ve  to  next  line; 


PushWord  '3 
CLC 

LDfi  VerlPos 
fiDC 

STfi  VertPos 
PHfi 

_nowcTg 


^Left  side 

!  (heigh t  ai  I ine) 
;  1  1  lip    n  Limber 


PLK 
INK 

CP!<  »1S  ;At    last   color  yet? 

BHE  ColorTffKt  ; No ,   so  branch 


RTE 
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TheTcxl         STB  'The  qLiicli    brown  fox  jumpeti.' 

■END 

Listing  6-6:     How  To  Define  and  Use  a  QuickDraw  PoIvRon 


DsfirtPoly  START 

;  First  move  the  pen  lo  the  desired  position; 

PuahWord   'ICQ  ;horizorIfll 
Pu  5hUor  d    '1?a  juertical 
_f1oveTo 

;    ...    IhETi  open   the  poll  ygon   record : 

PHfl  jspacc    for    result  (handle) 

PHfl 

_DpenPoly 

PcpLong  PolyHndl  ;Pap   the  palygon  handle 

;  -..  IhffTi  draw  the  outline  of  the  polygon  with  Line  or  LintTo 
J    (this    defines   a  pentagon): 

PuahW^-ord  '5C 
PushUlord  #Q 
_L  1  ne 

PuahWord  *^S 
PushWurd  *-25 
_L  1  ne 

PuahWord  '-50 

PtishWord 
_L  1  ne 

PushUord  J'-SO 
PtishWord  *25 
_L  1  ne 

PushWord  "  *.25 
PushWcird  #25 
_L  1  ne 

;    ...    then    cloEe    the    polygon  record: 

_CloscPaly 
BTS 
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;   To  display  the  polygon,    call  ShowPoly: 
SbQwPoJy  ENTRY 

PushLorig  PulyHndl 

_PairitPaly  :(or  Frame,    Erase,    Invert,  FiU 

UTS 

;   To  permanently  dLspoac  of    the  polygon,   call  ByePoly: 

ByePoly  ENTBV 

PnahLong  PolyHTidl 

_,KillPoly 

RTS 

PatyHndl       DS  4  jHandle  to  polygon  rcccfd 

END 

Listing  6-7:    Thtf  TextReader  Program  


TcKlReader  * 

•  Jhi.^  program  demonstrates  how  to  deal  • 

•  with  window!    that   have  scroll   bara.  * 


MyCode 


Tc)(tHndl 
TextPtr 


LIST  OFF 

SVMBQL  OFF 

A8&ADDR  DM 

INSTIME  DN 

GEN  ON 

KEEP  WIND 

;  Object  code 

MCOPY  WIND.MftC 

;  M-a  c  r  0  file 

START 

page  global  equates: 

GEQU  (0 

iLDNG 

GEQU  *4 

;LDNG 

Lfiing  GlobalData 
Using       Start  Da ta 

J5R  DoStarlUp 
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;  Define  end  display  the  fhEnLi  bar-: 


PdshLong  '0 
PuBhPtr  McnuLE 

_Ne'wMen[i 
PaahWord  i'O 
_lTi5er  IMeng 

PnahLong  tO 
PushPtr  MenuLI 

PaihWord  '0 
_lTi5er  tMcTiu 

PushWord  *1 
_F  1  xflpp I eMenu 

PHA 

i  xPlemuBar 
PLA 


;Adct  OAs  to  Apple  me-nu 
iRdJuat   size  of  menu 


_D  rawMenuBar 
1  Save  the  currcTit  direct  psge 


TDC 
STA 


MyDP 
InitCursnr 


;  Turn  on  arr  dw  cursor 


!  Ask  the  user  for  the  nartie  of  the  ^ile  tfl  Op^n .  To  do  XhiB 
;  use  the  STQefFile  dialog  box  ^see  chapter 


CetName 


PuahWard  r^2a 
PughWord  »'4C 
PushPlr  SFPr-ompl 
PushPtr  FilterProc 
PushLong  #0 
PuahPtr  ReplyRec 


LDfl 
BME 
JMP 


good 
Lsadl t 
Do5hutDowTi 


-y 

; pr  orapt 

; f  1  1 ter  prgcedurc 
; ( no  file  type  list) 
;reply  record 


;|jet    the  resLilt 

iBrarch   if   it  was  ''open'** 


;  Load  a  text  file  irto  memory.  This  is  dure  usiTig 
i    ProDQ5   16  CQmrnands    (see   chapter  10): 

Load [ t  _DP£N  GpenPsrms 

LDfl  refnum 
STfl  refnuml 
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STfl  refnumS 
STA  refTiuin3 
STfl  refnumi 


GETEDF  EQFParma 


PushLoing  '0 
PuihLong  FileSize 
PuahWord  MylD 

Pu^hUord  fieoaa 

PushLoTig  /C 

PapLong  TtxtHnd! 


; space  for  result 
i  Puah  mi 2e  of  file 

;  Lac  li  cd 

;(meari!  rothing  hirt) 

jSave  hafidLe  Id  text  arta 


LDA  tTextHrdl]  ;  der e f e r ence    the  handle 

STfl  TeKtPtr 

STA  data.biaf  f 

LEY  *2 

LDA  [TeKtHrdn.Y 

STft  TeittPlr»2 

STA  data  buff*? 


LQA  Fi ieSize 

STA  request 

LDA  FiteSize*? 

STA  reqiisst  -2 


NFULINE  NLParma 

HEAD  ReadPerms  ;Read  data   m  to  TextPtr  block 


;CBlciilal^  af  document   (In  pixtl    lin^i).  Thia  la  dont  by 

^    mnj  H 1  p  1  y  ing   the  niimbcr  of  Carriage  Returns  hy  9   (the  height 

5    of  a   1 1  he  )  : 


STZ  DocSwe 

LCY  'C 

GetSize         LDA  [TextPtr].^  j&et    next  character 

CMP  (-lOD  ;End  of  line? 

BUE  Skipinc  ;No,   50  branch 


CLE 

LDA  DocSiie 

ADC  03  ;9  plxela  per  line 

STA  QocSiie 


supine  INY 

CPY  FileSize  ;fit    end   of  file? 

BNE  GetSiie  ;No,  ao  branch 
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GLC 
LDA 
ADC 
STfl 


Dec  S 1 


^Provide  i         1 1  boltom  margin 


CUp  to  max  d^plh  o-f  1 EK  (11000}  be'Cfiu^?  of 
QuiclDr^w  boundary  reitrlctions; 


CMP  *S3FFF-9 
BCC  ShowUind 


iLarger  than  max' 
iMo ,   90  branch 


LDfl  /*3FFF-9 
STfl  DocSize 
Defj.ne  and  display  the  windcwi 


iCLip  to  majc  [subtract  9  to  avoid 
;  adverse  effects  or  last  Jiine] 


;Space  for  result 
jPointer    Id   wmdow  record 


ShawUmd  PHA 

PHfl 

Pu  ahP  I  r     fifl  1  nWlTidow 
_N  ewW  I  Tidow 

PopLong  UindakuPtr  ;Sak/e  pointer  to  wirdo-w  record 

;  Change  the  title  of   the  window  to  the  name  of  tht  file! 


SfltTitle       PushPlr  Filename 

PuahL-OTig  Ui  ndowPt  i 
_SetWTitle 


E^/lLoDp  PHfl 

PuahUord  #SFFFF 
PushPtr  EvertGec 

Ta  9  l[Mas  Itr 
PLfl 


J  fl 1 1    event  5 


;CEt  result  cade 


GMP  'nil  fiMetiisBar 

BEQ  DoMenu 


iMenu  item  select ed? 
; Vea ,   sd  branch 


CMP  'wl nGoflway 

BNE  EvtLaap 


;  I  n  close  box' 

ilgnors  everything  elae 


PuahLong  TextHndl 
_Di spo  seHandle 


;Frea  up  text  block 


PushLong  WmdowPtr 
_Ci  oaeW.L  ndow 
BRL  CetName 


iDelete   the  window 
J  Go  get  another  file 
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i   Handl*  menu  s&lectiona; 


LDA 
flHD 
flSL 
Tfl)( 
JMP 


fMenLiTable  ,X[ 


iConuert  to  0  base 
;x2  to  step  irto  tabl^ 

^.Cflll  m«TiLi  item  handler 


PlETiuiTabiE  DC 
DC 


I ' Doflboul I 
I 'DoQuitl  I 


DoAbou  t ] 


DoQult I 


JSR 
JSR 

jnp 


FixMTit Is 

t  Locp 

EJoShutDown 


FixMTltle     PLiahUord  *Fal5e 

PiiahWor d  TaskDatatS 

_H  I  i 1 1 eMenu 

RTS 


^Highlighting  off 
;Oet  menu  ID 


END 


-,  Ta^kPlaater  caila  this  routine  whenevef  an  updati^ 
;    e^ent    occurs.    It    is   responsLbie  for   redraw iryq  the 

;    contents   af    the  wirdow. 


WiTidUpdate  START 

Using  Gl'ObalData 

;  Mate  the  data  han+;  equal  the  code  banl:  ao  we  don't  have 
;    Id  uae  absDlute    long  addreasing: 


PHB 
PH< 
PLB 


;data  bank   ■  code  bank 


;  Switch  to  the  direct  page  the  application  a%ei  so 
;    that    we   can   ii^e  TextPlr: 


PHD 
LDfl 
TCD 


MyDP 


;  Seiup    Cur  re  n  L  DP 
;  5"i  t  c  h   t  g  -our  DP 


i  Oet  Ihe  current  value  of  the  PortRect.  PortRe-ct  I5 
;   the  rectangle  describing   the  content  regmn. 

PushPtr  PortRect 
.GetPortHect 
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1  Seen  for    the  firat    Litis   in   the  document    that  will 
appear   in  the  windnuj; 


LDA 

STA 
LDV 


VPos I tl en 
'%VVFF 

FSC 


iCoord  of    L 1  nip  *0 


FindStart  LDfl 
PHV 
AND 

crtp 


[TextPtr] ,V 

.rl7r 

FSl 


lOet  character 


: End  of    I  1 ne' 
;No,    50  branch 


FSt 


CLC 
LDfl 
ftDC 

LDfl 
GflP 
BC5 

PL¥ 

GFV 
BHE 


yPos 1 t ion 

YPos 1 1  ion 

YPoa it  ion 
PortRect*top 

FS2 


FindStart 


iAdd  height  of  line 


;Get  positioTi  in  docutrienl 
?Pa5t    the   top  of  PortRect' 
ifes,   so  we're  ready  to  start 


;ftt  end  of  f i le7 
■;  No  ,    30  branch 


PLD 
PUB 
RTL 


PLY 
INY 
PHY 

PushUord  *2 
PuahWord  YPos  i  t  i  on 
Mo  To 


;Mowe  to  l5t  character  of  line 
iMowe  to    left  edge 


PLY 


f  Deterr^ine  the  niidiher  of  bytes   in  Ihc  line 

i  as  that  ue  cdn  dr^M<  them  all  at  orice  with  DrawTexl: 


HcxlLlnc 


5TY 


StartPoa 
Count  er 
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ShowL  1  Tie 


AMD 
CMP 
BEQ 

INC 


[TextPtr] ,Y 
'SOD 

Counter 


;Get  character 
iStrip  high  bit 
^flt  srd  of  line? 
iVes,   %Q  braTtch 


Co  tLi ne 


IHV 
CPV 
SHE 

DEY 

PHY 

LDfl 


ShowL  lT\e 


Counter 
OolLi  nel 


CLC 

LDfl 
ADC 
TflK 
LDfl 
ADC 
PHfi 
PHX 

PuahWord  Counter 
DrawTex  t 


StarlPos 

TextPtr+2 
#0 


Go  t  L  1  ne1 


CRLF 


■,flt  end  of  file? 
1  Nd ,    5 o  branch 


iCF  by  Itself 

lYea,   ao  don't  draw  anything 

tPuah  alartifig  posilum 

;  by  adding  offset   to  TextPtr- 


;Number  of  bytes   to  draw 


J  Move  to  neitt  line 


i   Checit   to  5ee   if  we've  gone  paat   the  bottom  of  the  window: 


PushPtr  PenPos 
Get  Pen 


Exit 


PLY 
IHY 
CPY 
BEQ 

LDfl 

CLC 
ADC 
CMP 
BC5 

PLD 
PLB 

HTL 


Fi  I  eSi  ze 
Exit 


;Gct   cuTcnt  poaition 
;&el    buffer    position  back 

;Ye9,  so  branch 


Por t Rec t +bo t torn     jGet  bottom  of  portRect 


'9 

PcTiPoa  *v 
Next  Line 


;gD  one    line  further 
jPbti  reached  bottom  yet? 
;Na,   so  branch 

;ReatDre  DP 

;  Do  not   use  RTE  M 
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PortfJect       DS  8  ;rectangit 

SlarlPos  DS  2 
CauTiter         DS  2 


■  This  is  the  filler  procedure  for  5F&etfiie.  • 
•   It  15  Explained   m  chapter  10.  ■ 


FillerPfoc  STfiRT 


Dun 

PHD 

;  Save 

direct  page 

w  p  n 

7CD 

;Ali>gTi  dip.    Kith  ^tack 

LDV 

;Qff5Et    to  file   type  code 

AHD 

;  (use 

tow  byte  only) 

CMP 

rtBO 

;Si;c 

f  i1e^ 

BE  a 

FPO 

;  Yes, 

so  branch 

CMP 

;TXT 

file'' 

BE  a 

FPO 

50  branch 

LDA 

*1 

1  f 

di^play/not  ^.electable 

BKA 

FPl 

LDA 

#2 

j2  ■ 

dlaplay/sel ectable 

PLD 

I  Rff-s t ore  d .  p . 

STA 

8,5 

the  result 

USA 

2,5 

;  Move 

3-byte  return 

STA 

G.S 

i   address  up  by  4  bytes  . 

LDA 

1  ,s 

STA 

5,S 

TSC 

;  Add 

A   lo  the 

CLG 

i    slsck  p-airter. 

ADC 

■4 

TC5 

BTL 

END 

•  Flcve  cursor   to  left  aide  of  next  line: 

C8LF  STftRT 

Us  1  ng       Globa 1  Data 
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PushPtr  PenPoa 

PushWord   *  2 
CLC 

LDfl  PenPos+v 
ADC  '9 

PHA 

_MoveTD 
PIS 


■,Get  currenl  pen  poaition 
ilF-ft  edge 


;9  L3  the  height  of  the  ayatem  font 
;heui  vertical  position 


END 

COPY         STANDARD.  ASM  ;Star>dflrd  star  tup /ahul  down 


ClDbsIOata  DATA 

;   Window  pa r amet er 5 : 


MyT I t 1 E 
Ma  i  nUi n  dow 


Page  Jumps 


;  Mbtiu  /  1  tern  1  l  a  t  a  1 
MenuLI  DC 


jPomter 

to  wiTliiaW 

DC 

n  '  0' 

■,Hull  name;   filled   in  later 

DC 

[2'WindEnd-MajnWindoui 

iSize  of  table 

DC 

1 '  XI 1 01 1 1  CI  1  01  001 01  ' 

iwindoiu  frame  tj^pe 

DC 

I A "MyTi 1 le* 

^Pomter   to  window  title 

DC 

II'O' 

;  r  B  f  c  OTi 

DC 

1  '40  ,4  ,18£.60S' 

;zoam  rec  ta'ngle 

DC 

1  4  '  D  1 

-color   table    (C    '  default) 

DC 

P  0,0- 

; document  offset 

DC 

I  "1  024  ^9EQ' 

; hei t  , w 1 dth  af  data  area 

DC 

1  '0,0' 

;  hei  gh t  ,  w  idth  may  wind&w 

DC 

1  '5,12' 

;vert,   horn   line  movement 

DC 

!  '  m  ,  S92  ' 

■jvert,   'horii  page  mavement 

DC 

H '  Q  f 

;  inf D  bar  ref c  on 

DC 

I2'12' 

(info  bar  he  igh  t 

DC 

]4'0' 

■  frame  def pr  qc    [ 0   "  stands 

DC 

14'0' 

1  inf c  bar  def proc 

DC 

|4'UindUpdatB< 

^content  defproc 

DC 

["ia,4,182,6(18< 

iConlent   region  rectangle 

DC 

141-11 

iflt   the  front 

DC 

M'O' 

iStorage    [use  MM) 

ANOP 

MeruLS 


DC 

DC 
DC 


I 


C'>  9\H1  )( '  ,H  '  OD'  ;''pple  menu 

C'#/flboiil    this  program   .  ,  . \N?56V  1  ,  H  '  QD' 

C'>     File  \N2i.HiaD'      ;File  meriLi 

C'*»0iilt\H2&7»0q'  ^H'OD' 

C  .  I  i  End  of  menu 
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MyOP 

DS 

Z 

YPoa  1 1 1  DTI 

DS 

2 

P  =  TlP05 

DS 

1 

;   SFGelFi ]e  da t a : 

SrPromp  t 

5TR 

'Se 

HeplyRec 

good 

DS 

2 

filelype 

DS 

E 

au  Ktype 

DS 

2 

F 1 L  eName 

DS 

16 

f J  1 Lpath 

DS 

129 

;  Data  for 

f 1 Ifi    1 /Q  op 

n  n 

DpenParms 

ANOP 

r  e  f  nam 

DS 

2 

DC 

H  ' 

DS 

EDFParma 

fiMDP 

re  f  Tium  1 

DS 

DS 

4 

AN  DP 

ref  num2 

DS 

DC 

13' 

DS 

ReadParm  a 

flWDP 

DS 

dsta.buf f 

DS 

4 

request 

D£ 

DS 

•1 

C 1  DseParms 

AMQP 

ref  nu  m4 

DS 

2 

jEvent  Record  for 

Tasi: 

Ever  tRec 

ANnp 

Mhat 

DS 

2 

Mes  sage 

DS 

4 

;Appii.c:ation's  direct  page 
jCurrent    pen  p-osilion 


Select  a  file    lo  vi ew : ' 


HoTi-iero   if  open  pressed 
ProDDS   f  J le  type 
ProDQS  auxiliary  file  type 
Hame    of    file    ir    prefix  0/ 
Full  pathnamr 


^diiable  reufline  read  mode 


^Pointer   to  data  area 


; Eve  nt    c  odp 
; Event  r esu 1 1 
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DS 

4 

jTicts    ^iTice  slartup 

D5 

A 

-.riouLSE   localion  (glgbdl) 

Mod  1 f le  r  a 

2 

;SlaHi9  of  modifier  fceya 

Ta  s  kData 

4 

; Ta* kMa s t cr  data 

DC 

lA' (OOOOIFFF' 

;Ta5kM^5ti^r  handles  all 

END 
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CHAPTER  7 


Using  Pull-down 
Menus 


One  ijf  tlif  difficult  dec-isiuns  .li  propramnner  laces  whew  de\'claping  an  applic.;itioii 
is  h(iw  (cj  di'-'iiiin  Hif  funimand  iiittHiwf  between  the  user  and  the  applkatiiin.  One 
i;chonl  nf  rhnught  "i'-iy^  ust-'i"  sIkhiIlI  he  forted  tn  memorize  cnmnianil  mimes  whidi 
must  he  typfd  in  fnim  the  ke>  beard,  'Die  advaiilage  of  this  fnmini>n  tt-thnique  is 
that  cHice  th('  toisinidnds  are  mastered.  the>  ciiii  he  entered  very  quickly.  Tlie  tvvo 
main  disLld\antai^es  art"  that  il  Lan  lake  a  Iciiip  time  to  niemurizt'  the  Liimniands  and 
[hut  Liimniands  are  easily  Jurjjotteii  if  a  program  Is  not  used  for  a  while. 

Till-  (ithcr  f\tr<Miie  ti'i  insifil  tlmt  the  user  must  always  s<=lett  a  iL'Oinin;ind  frimi 
a  displayi-d  of  pttssihli-  chok-L-s.  Siieli  a  list  is  called  a  mrnu.  This  teehnique  is 
p*!piilar  with  iLsers  whn  are  just  leaining  how  to  iisc  a  prt>jiram,  lieeause  lill  the 
e(iininiuiri.Ls  arc  iinniediately  obvious.  The  disadvantage  is  it  liecunies  lediuus  to  i.all 

and  hunt  through  a  menu  once  you  have  mastered  the  projlram  and  knuw  osaetly 
wliat  you  want  to  do. 

11  vou  ^allo^^'  Apple's  standard  user- interface  Ruidelines,  vati  will  implement  the 
menu  teelinifpie  with  c.s  applieationK  that  use  the  super  liiRh-resolulioii  desktop. 
To  define  menus  and  handle  menu  activity  in  standard  tt-ays,  use  the  Menu  Manager 
tiHit  set  (tool  set  15), 

Despite  its  name,  tlie  Memi  Manager  iioi?s  make  cwiicessiuns  to  the  counniind- 
driven  interface  heeansc  yon  can  (lutekly  select  t-ertain  menu  items  by  pressing  a 
character  key  while  holding  d(jwn  thi-  Open-Appltf  [Coroitiatidl  key.  Such  a  key  is 
c-alled  a  keyboard  atrnvak'nt, 

The  names  of  each  menu  defined  by  a  GS  application  that  uses  the  Menu  Manager 
appear  in  a  reetangidar  menu  hnr  acrnss  the  ti>p  of  tlie  [jraphics  sereen  (see  figure 
7—1).  A  user  can  see  the  contents  of  a  particular  menu  by  moving  the  mouse  cursor 
over  that  niemi's  tide  and  holdintj  down  the  muuse  button.  This  eauses  a  rectangle 
containing  the  names  nf  all  the  items  in  tlie  menu  to  appear  l^elow  the  menu's  title, 
(Because  the  cflecl  is  like  pulliiif^  duwn  a  window  blind,  a  GS  nienn  is  called  a.  j/ull- 
dtnin  memi^)  The  items  are  stacked  vertieally. 
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Figure  7-1:    An  Apple  IIf;s  Menu  Bar  antl  a  Pull-down  Menu 


Once  the  menii  has  been  pulled  down,  a  user  can  select  an  itt-in  by  maving  the 
mijuse  down  nr  ujj  (o  highUghl  the  appropriate  item  name  and  then  releasing  the 
mouse  butttm.  The  user  tan  aho  inspect  an  adjacenl  menu  bj  inovins  tht  mouse 
[with  the  button  still  down]  to  the  left  or  right  while  it  is  in  the  rnenu  bar  area. 

Tliis  t'hiipter  eovers  iniplementinn  pull-dnwn  menu.?  in  GS  apptieations.  creating 
bikI  displaying  menu  bars,  and  euntrolling  the  appearance  al' individual  itein^i  inside 
menus. 

STARTING  UP  AND  SHUTTING  DOWN  THE  MENU  MANAGER 

fust  Hfi  with  any  tool  set,  the  Starl-Up  fLiiiLlinn  inu^t  be  called  In-fcire  the  Menu 
Manager  ean  be  used.  The  Fiintlion  name  is  Menu  Startup.  Hefore  calling  Memi- 
Startup,  buweV'er,  you  mti-st  start  up  QuiclcDrEiw,  the  Event  Manager,  and  the 
Window  Manager — the  Menu  Manager  uses  these  tool  sets  to  perform  some  of  its 
funLtions. 

Here  is  how  to  start  up  the  Menu  Manager: 

PushWord  MylD  jProgram   ID  (froni  tlMStartup) 

PiishUlord  DPAddr  ;Adclre55    ai   tJirect   page  area 

_rnienii£lar  tup 

DPAddr  points  to  a  one-page  area  in  bank  z«ro  of  memon.'  that  the  Menu  Manager 
uses  for  direct  payje  storage.  U.sc  NevvHandle  (o  allwate  ibis  space. 

MeiiuSlartup  perlonns  aJI  the  housekeeping  needed  to  gel  the  Menu  Manager 
up  and  running.  This  function  creates  an  empty  system  menu  bar,  makes  it  the 
eurrenf  menu  bar,  and  displays  it  at  the  top  uf  the  screen. 
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Just  before  your  program  ends,  c^Il  MenuShutDown  to  free  up  the  memoi^'  areas 
used  by  the  Menu  Manager.  It  requires  no  parameters  and  returns  nn  rcsultii  on 
the  stack. 

CREATING  A  MENU 

To  create  a  menu,  use  the  NewMtnu  tiinftion.  It  requires  only  one  parameter — a 
pointer  tn  a  tnenu/itcm  line  list — and  returns  a  handle  to  (he?  menu  reeiird: 

PHfl  ;spflCHforri?^Li:t[long} 
PHfl 

PushPtr  MenuLtst  iPointer   to  Tienu/item  list 
_NewMe  nu 

PopLong  MenuHndl  ; Pop  handie  to  the  meru 

Make  sure  yau  save  the  handle  returned  by  NewMeiiu  because  ynu  will  need  it 
when  you  add  the  menu  [o  the  menu  bar  with  IniertMenu-  Note  that  if  the  handle 
is  0,  the  menu  could  not  he  alliKated.  either  tieeause  there  is  Tio  memory  available 
or  because  the  meniWiteni  iine  list  L  invalid 

The  menu/item  line  Hst  is  a  series  of  lines,  each  followed  by  a  null  (ASCII  $00) 
or  a  carriage  return  fASClI  $0D).  A  typitial  list  looks  something  hke  this,  in  assembly 
language  format: 

TheMerd  DC  C  »  Edit  H,N3M1'0' 
DC  C'##Urido\H256Vi  ,11  '0' 
DC  C'##Cut>\N257'  ,11  '0' 
DC  C'##Copy\H25e' , M '0' 
DC  C'?>'#De:ete\rt259i  ,11  "Q' 
DC  C  .  ' 

The  first  hne  in  the  list  dcfim:s  the  title  for  the  menu^  the  first  character  {>)  informs 
NewMenu  that  this  is  a  menu  title,  nut  an  item  name.  It  is  followed  by  another  > 
character,  which  simply  acts  as  a  place  hoJder  for  the  length  of  the  string.  (The 
Menu  Manager  fills  in  the  length  wlien  you  ciil!  NewMenu.)  The  menu  title  itself 
comes  next,  terminated  by  a  backslash  and  some  special  characters  defining  the  ID 
number  for  the  menu.  More  information  alwjiit  these  special  characters  is  gjvea 
below. 

Notice  that  there  is  une  ^pace  to  the  left  and  one  to  the  right  of  tke  title  name. 
This  is  nnt  required,  but  it  provides  aesthetic  gaps  between  adjaient  menu  titles  in 
the  menu  bar. 

Subsequent  lines  define  menu  items  in  the  i>rder  in  which  they  are  to  app^-ar  in 
the  menu.  Each  line  begins  with  an  item  t-baraeter  (#)  that  must  be  difierent  from 
the  menu  title  chiiracter.  Fnllnwin]^  it  are  a  duminy  place  holder  character,  the 
name  of  the  item,  and  a  terminatinig  backslash  followed  by  special  characters. 
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Thf  list  is  termiiiiited  by  li  Lliarafter  (.1  that  is  tiiftt-renl  froiTi  the  itiftiu  item 
charatttT  liiit  could  bf  the  siLnit  as  the  menu  titlf  tharacler,  In  fact,  if  yuu  are 
dcfFiniiig  several  meiiu/itcm  lists  in  sequence,  the  menu  title  character  for  the  next 
li.'it  can  be  used  US  a  terminator  for  the  turrrnt  list,  Just  be  sure  to  follnw  tht  last 
hst  with  A  terniinatOT  character. 

By  the  way,  there  is  nothing  magical  in  the  three  fharatters  used  in  this  example. 
Any  characters  may  l)c  used,  as  Ions  '''t-  menu  item  charactrr  is  different  from 
the  menu  title  charueter  iind  the  terminator  Lharaiter  is  different  from  the  nifnu 
item  character. 

Following  each  title  and  item  name  in  the  list  is  li  backslash  character  (\),  The 
hatkslash  signifies  the  enJ  of  the  menu  or  item  name  and  the  be^iniiin;^  ol  a  series 
of  special  characters.  In  the  example,  the  special  characters  are  nf  the  form  "Nsxs" 
where  "ssx"  rcprcsei^ts  a  deeijniil  ID  numher  fcr  the  title  or  item.  Other  special 
characters  ynu  tan  use  are  snmniarized  in  table  7-1.  Moit  t)l  them  afiect  the 
appearance  of  the  text  in  the  line. 

The  program  in  lisling  7-1  shtm  s  how  to  create  three  standard  types  of  menus; 
an  Apple  menu,  a  File  menu,  and  an  Edit  menu,  each  using;  Menu  Manager 
functions, 

ID  Numbers 

Evtrrv  menu  title  tiame  must  he  asscx-iated  with  an  ID  number  from  I  to  6.5535. 
None  nf  these  nunihers  arc  reserved,  but  each  niCTiu  title  must  have  a  unique 
mimlier. 

The  ranRe  ot  ID  numbers  permitted  far  item  names  is  narniwer.  The  numbers 
frmn  1  tu  249  ture  reserved  for  use  by  desk  accessory  items.  The  numbers  from  250 
to  2;55  are  reserved  for  special  editing  items  and  a  Close  item,  which  are  often 
needed  h\'  desk  accessories: 


Undo 

250 

Cancel  last  editing  nperation 

Cut 

251 

Cut  selected  text,  put  ft  on  the  clipbuard 

Copy 

252 

Copy  selected  (exi  to  ihe  clipboard 

Paste 

2!i3 

Transfer  text  Irnm  the  tlipboard  lu  the  document 

Clear 

254 

Cut  selected  text:  do  nnt  put  it  on  tlie  clipboard 

Close 

Close  the  active  window 

(The  clipboard  is  a  data  area  maintained  by  the  Scrap  Manager.  It  facilitates  the 
movement  of  data  within  an  appHcation  or  from  one  application  to  another.) 

The  first  five  items  t(hould  be  [jlaccd  in  a  menu  culled  Edit.  The  Close  item 
should  be  plated  in  a  jnenu  called  File. 
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Table  7-1:     Special  Chsirafters  for  Memi/Itein  Lists 


Special 

Character  Sfi'tiitiii^  

\  Beghmliig  uf  speuial  characters 

•  Keyboard  eqiuvalcnt  characters  ft>]lt>w 

(primary  followed  hy  idtcrnate) 

B  Boldfiice  the  name 

C  Mark  character  folUiws 

D  Disable  (dim)  the  name 

K  Two-byte  liinsm'  ID  nmnher  fnllows 

($0001  ta  SFFKK,  low-order  byte 
first) 

I  Italicize  the  name 

N  Detimal  ID  ciumber  follows  (1  to  B5535) 

U  Untterbne  the  name 

V  Pul  a  dividing  Itne  under  the  name 

{but  do  not  use  a  separate  item} 

X  U^ie  color- replare  highlighting 


NOTE:  All  these  fp«cil<l  char-icters  may  ht  iiit-il  wilt:  ilcm  iiatiies.         only  V  D.  (I ,  N.  iknd  X  with  iiirnu 


When  thfsf  ID  luiinhers  ,irc  assigned  tn  these  ilrm:s.  and  a  TaskMaster  event 
loiip  ii  LisL'il.  [he-  S|itfdal  items  will  LiutnniaticalLy  be  pasii^d  tn  an  autive  desk  accessory 
far  pnieessinf;.  Se<?  thaptcr  9  liir  inure  inlorniation  on  desk  iicLessuries. 

The  rest  of  the  ID  nnnibers.  fnsm  25fi  to  65505.  may  be  used  by  the  application 
in  iinv  wi\y  it  sees  fit-  Kec|)  in  miiiil,  hiiwever.  that  each  menu  ileni  mnsl  htive  a 
Lniqiie  ID  number,  althmijjh  permanently  disabled  iteni:^  may  share  the  same  ID 
number. 

When  you  are  defiiiinj;  a  series  nf  nwiins,  ynn  miijht  want  to  number  the  items 
consetutively  from  25(i.  This  makes  lL  possible  to  actesa  the  subroutine  to  be  tailed 
when  the  item  is  selected  by  doublhifi  the  low-order  byte  of  the  item  number  and 
using  the  resiult  aa  an  inde!(  intn  ii  table  of  two-byte  subroutine  addresses.  The 
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statidiird  Edit,  File,  and  Desk  Acccssnry  items,  vvhiL'h  have  numbers  below  256, 
would  be  treated  as  special  cases. 

H'Cre  is  i  code  Fragment  thit  illusbrates  this  technique: 

i   Enter  here  fith  the  menu   item  niimber  in  A; 

CMP  #2EG  iSlandard  Edit,    ClQse,    ar  DA-* 

BCC  DoSpeckal  ;Ves,   so  branchi 

AMD  #S00rF  il50lflte  low-ofder  byte 

ASL  ;D<]uble  to  get   index   into  tabli? 

TflK 

JttP  ( ITEM.TBL  ,  K  )  ;Pass  control   lo  item  tiandler 

DoSpei:  lalHOP  ;Handle5ppclfllca9e5here 
RTS 

ITEM.TBL     DC   1 2  '  Da  1 1  em^SS  '  ;Rddrea4  of   item  #25E  tiandler 

DC    12'Doltem2&7'  ;flddre5S  gf    Item  handler 

DC    I2iDQllem2S8'  ;flddres6  af    11^*  #25B  handler 

You  can  use  the  H  special  character  to  specify  the  ilem  or  memi  tuiiidxr  in  binarv', 
rather  than  decimal,  furm,  If  you  use  the  H.  follow  it  with  the  two-bytc  binary 
numhcr,  low-Drdt-r  hyte  first.  For  exainple,  to  assign  an  item  nunibpr  nf  ^■OlDa, 

specirv'  an  itt'iii  liiif  oi  the  lilinil: 

DC  Ci##The   Jt=i3i\H'  ,H'03  Q1',J1'0i 

You  could  also  use  12'§0103'  instead  of  H'03  01'. 
The  Appearance  of  an  Itc^m 

Several  special  characters  can  be  used  to  affect  the  appearance  uf  an  item  in  a  menu. 
The  program  in  listing  7-2  indicates  h<iw  to  use  them. 

'Iliree  s^pecial  tharacters  are  available  fur  .selecting  the  t>i3efiice  ol  an  item  name: 
B  (boldfaced).  I  (italicized),  and  U  (underUned).  For  example,  to  atttich  all  three 
faces  to  an  item  with  an  ID  of  323,  put  the  tbiltiiwing  line  in  the  meEiu/ilem  line  list: 

DC  C'##My   Itern\N323SIU>  .  II '01 

Note,  however,  that  the  standard  .^^ystein  font  used  b>  the  GS  cannot  be  uutledined. 
Fiirtherinure,  current  versions  of  QnickDraw  dt>  not  j^npport  italicii 

To  disiilile  an  item,  nse  the  special  eharaeter  D,  A  disahled  ileni  is  dimmed  in 
the  menu  and  cjinnnt  he  selected  when  the  user  pulls  down  the  menu.  You  should 
disalde  an  item  whenever  the  action  assoLiated  with  il  is  not  appropriate  in  the 
cuiTent  cnvirimment.  For  example,  if  vou  have  iui  iLein  tailed  Open  Window,  and 
the  window  is  already  open,  you  should  disable  the  item. 
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DividinK  lines,  used  tii  separate  enmps  ol  rclntfd  items  in  a  mmii,  should  always 
be  disi^bled.  Here     how  Ui  define  a  dhahU'd  dividing  liju:  in  a  nicjiu/item  line  list: 

DC  C'##-\N3£4D'  ,  11  '0' 

The  Menu  Manafjcr  iiiteqirL-ts  a  siiij;le  hyplifn  AS  a  row  of  hyphens  extending  across 
the  width  of  the  menu. 

You  can  also  t-reate  a  dividing  line  with  the  V  siKcial  character.  This  iypc  of 
div  iding  line  is  realU'  jusl  an  uiidt-rlii^t'  and  so  does  not  use  up  the  spai-e  nf  nn  entire 
itejn.  The  main  advanEa^e  ol  using  it  instead  oi  a  true  dividing  line  is  that  ynu  uu.n 
fit  more  menu  items  in  a  inetitt. 

The  \  specinl  tliLiracter  denotes  a  spedul  fnnn  nf  hiKWiEhfin^  to  he  nsed  when 
a  menu  title  ur  a  menu  ileiii  is  selec-ted.  Tlu-  defaidl  highlighting  inethnd  is  called 
XOR,  which  causes  a  uainc  to  be  inverted,  When  an  X  special  character  is  specified, 
cphir-repfGcc  hijihlighting  is  iise^tl  ini^tejd  uf  the  XOR  method;  this  method  caiises 
only  Ihe  white  baekgrou  nd  of  a  mlDreil  iihjett  tn  he  inverted. 

You  will  iJsecolor-repUce  IiiKhhylitiiig  for  a  menu  whose  title  is  the  eoiured  Apple 
logo  By  convention,  this  mcnn  appears  nn  the  left  side  uf  a  menu  bar  and  eontains 
the  names  nf  all  the  active  desk  aLtessorieii  in  the  system  and  an  "About..,  '  item 
that  displays  information  aliout  the  proj^ram.  To  define  the  title  for  the  standard 
Apple  menu,  use  llie  fnllHwin^  line; 

DC  C'^>!i?\HI  X  '  ,  n  '0' 

The  Menu  Manaj^er  substitutes  the  colored  Apple  logo  tor  the  (O'  character,  as  long 
as  there  are  no  additional  spates  on  either  side  of  th«  menu  title  character  (@), 

Keyboard  Equivalents 

As  you  will  see  later  in  this  chapter,  a  user  may  select  some  menu  items  by  pressing 
a  character  key  "hile  holding  down  ihf  Open-Apple  modifier  key.  Use  the  *  special 
character  to  assif^n  two  keyboard  equivalents  to  a  menu  item.  The  two  characters 
immediately  following  the  *  are  the  primary'  and  alternate  keyboard  equivalents. 
The  primary  character  is  showio  lo  the  right  of  the  item  name  when  the  menu  is 
pulled  down. 

If  the  primary  keyboard  equivalent  is  an  alphabetic  character,  it  should  be  in 
upper  case  Tbc  aheriiate  equivalent  should  then  be  set  to  the  ccirrespimding  lower- 
case character,  [iere  are  some  examples: 

DC  C'##C4t \N2S6*IC3i^  ,  1  1  '0' 
DC  C'##HelpV,N303'?/'  ,  11  'O- 

Notice  the  two  standard  keyboard  equivalents  fur  a  help  item.  The  primary  character 
is  ?  and  the  alteniLite  is  f.  Because  these  two  characters  are  associated  with  the  same 
key,  help  will  arrive,  notwithstanding  the  status  of  the  Shil't  key. 
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Marking  [(ems 

Thf!  final  special  chau-aftcT  is  C,  ll  is  used  to  marl;  an  item  liy  placing  a  special 
t'haract-cr  to  tlie  left  of  its  name  in  a  menu.  By  conveiilitm,  an  item  is  to  be  marktrd 
unly  if  a  featur<?  asiiJCia,tL'd  with  it  is  at.tive,  or  nil.  For  instanct-.  if  you  have  a  menu 
of  font  sizes,  the  one  that  is  currently  active  should  be  marked  and  the  others 
Unmarked. 

Here  ii  an  item  line  defining  an  item  marked  with  the  character  x: 
DC  C '##UTidier  1  ine\N322C>t '  ,  I  T  '  0* 

A  more  comiiioti  mark  character  is  the  checkmark  (ASCIJ  IS),  but  you  cannot  put 
il  directly  into  item  lines  because  it  is  not  a  standard  keyboard  character.  Once  llie 
menu  bas  hc.cn  defined,  you  can  set  the  mark  character  lo  a  checkmark  witli  the 
CheckMItem  functioji  (see  the  section  belaw  on  "Checking  and  Milrkin^"). 

CRE.\TI.\(;  THE  MENU  BAR 

Once  you  have  defined  a  series  of  menus  with  NrwMRnu,  you  are  T-^ady  to  add 
fbem  to  the  system  menu  bar.  To  do  this,  use  the  InserlMenu  function: 

PuahLoTig  MenuHndl  iHandle   lo  menu   to  be  inserted 

PushUord  #Q  jitiaerl  at   left  aide  of  meriu  bar 

_ J  nsertMenu 

The  sefond  parameter  passed  tn  InsertMeiiu  is  the  ID  of  the  menu  after  which  the 
menu  whoyc  handle  is  MenuHndl  is  tn  be  inserted.  H  the  nundier  is  0,  as  in  the 
example^  the  menu  is  inserted  lieforr  (he  first  menu  in  the  menu  bar,  Th^-  ca-siest 
way  to  add  a  ^roup  of  menus  to  th**  menu  bar  to  insert  them  in  order  from  right 
tn  left,  using  a  0  ID  piirameter  each  tinn'. 

If  your  menu  bai  iufludes  ^u  Apple  menu,  defiiLed  by  a  »Co'\NlX  line  in  the 
menu/item  line  lisi,  you  shoifld  add  the  names  of  all  the  active  desk  aceessuries  to 
it,  at  least  if  the  applications  plans  hi  support  aw-essoiies.  Do  this  usin)^  the  Fix- 
ApplcMeini  function; 

PushWcrd   #1  ;Menu  ID 

_F  titflpp  1  eMe  nu 

The  piuametcr  passed  to  FixAppleMeiui  is  the  ID  number  of  the  menu  to  which 
the  name!^  of  the  desk  iiccessor\'  items  are  added.  Tfie  desk  accessories  are  given  a 
consecutive  set  of  ID  numbers,  hcfiitniin^  with  1  ID  numbers  from  1  to  249  are 
reserved  fur  use  by  dcik  accesjiorit  s;  when  TaskMastcr  determines  that  you  have 
selected  a  desk  ac-tessary  item,  it  automiitieallv  <ipens  the  desk  accessory  for  you. 
Sec  chapter  9  for  more  on  desk  acccjisnrird*. 

Ont*  all  the  menus  have  been  added  to  the  bar,  you  must  call  KixMenuBar  to 
permit  the  Menu  Manager  tu  calculate  the  height  of  the  menu  bar  and  menus  and 
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the  maximum  width  of  each  menu,  The  Menu  Manager  needs  iHis  inforinatinn  sto 
that  itcandrHW  the  menu  bar  properly,  FixMfnuBar  returns  a  parameter,  the  ht-ight 
of  the  mcnii  har„  so  you  call  it  follows; 

PHfl  lapace  for  result 

_F  1  icMBTiLiBa  r 

PLfl  rP°P  height   of   msnu  bar 

The  application  probably  will  not  need  to  know  the  height  dF  the  menu  bar,  so  you 
can  dist^rd  the  result  Ytiu  musi  laW  FisMeiiul3ar  everv'  time  you  chansr-  an  item 
name  nr  menu  title  sn  that  the  Menu  Manaj^er  tun  adjust  iti  internal  record  uf  the 
menu  dimensions  accordinfjly. 

You  are  now  ready  lu  display  the  menu  bar  on  tbe  screen.  For  tliis.  use 
DrawMcnuBar — it  requires  ntt  paianiettri. 

Tlie  prcfi^rani  in  listing  7-1  above  illustrates  how  to  create  and  display  a  menu 
bar. 

Changing  the  Name  of  a  Menv 

If  yoii  wish  tn  change  the  name  of  a  menu  ai'tur  it  has  been  defined,  use  Set- 
Men  uTitle: 

Pu5tiPtr  HefwTitie  ;poirtEr   to   name  ^tnrg 

PustiUord  #2SS  ■.Menu.   ID  cade 

_Se  tMenuTi 1 1 e 

NewTitlt  3TR  'AMewTitle' 

NewTitle  is  a  strinj;  that  is  preceded  by  a  length  byte.  Call  DrawMenuBar  to  redraw 
the  menu  bar  after  thanging  the  name  of  a  title. 

CHANGIXG  ITEM  ATTRrBlfTES 

An  explauistion  iif  luiw  to  u^e  spfiial  characters  in  the  mciiu/item  Hne  list  to  set  the 
initial  appearance  of  a  menu  iWm  was  given  earlier  in  tbis  ebipter.  Voii  can  also 
Lhanse  an  item's  appearance,  or  its  name,  aflcr  the  menu  has  been  created,  using 
several  Merm  Manager  functions.  Those  functions  are  tbe  subject  of  this  section. 

Changing  the  Name 

To  change  the  name  of  an  ittm.  use  SetMlten]  or  SetMltemNanie,  SctMitem 
requires  two  parameters,  a  pointer  to  the  new  item  line  and  tbe  ID  of  the  item  to 
be  renamed: 
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P  u  ah  P  t  r      NewL  me  ;  Foirter    to    ne*    item  line 

PuahWord  #256  ; i tem  ID 

_Sie  tPI  1  t  em 
RTS 

NeuLjne    DC    C"i*#fi    Different  Name'JI'O' 

Till'  first  twn  characters  iti  iIk'  string  for  the  m-w  nuinr  {##  in  tUv  t-Nampli-)  are 
always  ij^norcd,  as  arc  any  characters  ftiHowing  a  \  eliaraLter,  and  ihe  S  charaeier 
itself.  Thus,  thp  npw  iteTn  name  will  have  the  sanii-  spet'ial  altrilmtcs  iiii  the  one  it 
is  repliiciiig. 

You  can  also  use  SetMItcmNainf  hi  change  thi"  name  of  an  itL-m; 

PughPtr     NewNamH  iPointef   to  new  string 

PushUord    #256  ^Item  ID 

_Setn  I  t  emHame 

RTS 

SlewHam#  SIR   'A  Different  Name' 

In  this  case,  tht;  first  paranu-ter  is  a  [Knintpr  tn  a  stjindard  ivlrine.  All  nthpr  item 
attributes,  siic-h  us  test  style  ant!  keyliTOrd  cfiiiivalcMits,  remain  unehangt'd. 

When  you  change  the  name  nf  an  item  in  a  mrnii,  the  width  nf  the  mtnu  may 
change.  a  result,  you  iiinsf  tall  CalcMeiiuSize  to  permit  the  Miinii  Manaser  to 
recalfulate  the  widlfi; 

PustiMord  #0  ;0  mean^:   calculate  defflult  widtti 

PuahWord  #0  :0  means:   calculate  default  heigtil 

PuahWord  #2'5G         ithis    is    the   menu  ID 
_Caicf1enuSi 

If  ytiu  do  not  call  CaleMennSize.  and  the  new  item  nyine  is  too  long,  some  of  it  will 
"spill  off"  into  the  hacksruund  whtii  yuu  pult  down  the  niemi. 

Enahling  and  DMablin^ 

As  mentioned  earlit^r  in  this  thapter,  an  item  L-an  be  disabled  or  enabled,  A  disabled 
item  is  ime  that  is  not  selectiihle;  it  apjieiirs  dimjiied  in  tlit  inenllr  Ail  enabled  item 
can  he  sdceted  and  appears  in  nnrmal  ?eript. 

You  shcjiild  disable  items  that  are  ni>t  relevant  ti>  the  aLtivity  eUrrently  in  progress, 
[f  you  do  wj,  the  user  eannot  waste  time  seleetine  a  meaningless  activitv'  lo  perform. 

Here  Is  how  to  disable  an  item: 

Pu^tiUord  #256  vltem   ID  rumber 

_Di  sebleni t  em 
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The  tcurespDndiiiS  enable  function  workii  similarly: 

PushtiJord  #2e6  ;Itfih   17)  number 

_E  nah  lefl  I  t  em 


Inserting  anrf  Delelmg 

T(i  iniif^rt  an  item  into  an  already-defined  iiifnu,  use  InsertMItciii.  It  requires  three 
puranirtrrs:  a  pointer  tu  an  itciri  lint-  di'fininf!;  the  mcmi  itrm,  the  \D  of  the  ile-m 
after  wljith  the  item  is  Lo  bt  inserted,  and  ihi-  ID  of  iht:  jneiiu  to  wliich  the  item 
is  to  be  added.  Here  is  how  to  call  InsertMIttrni: 

Pu  ahP  t  r      It  emEn  t  ry  ^Pointer    to    it  em  line 

Pu  5  hUor  d  #257  j 1 1  em  number    to  add  after 

PuahWord  #3  iMenLJ  number  to  add  lo 

_Inaerth1It  era 

RTS 

I  t-BmEnt  r-y  DC   C  '       1  n^er  led    1  t  em\N333'  >  I  1  '  Q  ' 

If  ymi  specify  ^ii  item  number  of  0.  tlie  item  will  he  inserted  at  the  top  of  the  menu. 
An  itpm  number  ul  ^jl'l'I-'F  eaiises  the  item  tu  he  added  tii  ihc  end  of  the  menu.  If 
the  menu  number  is  0.  the  first  menu  is  seWted. 

The  new  itt'iu  deRiiitiuu  [Hiinted  to  by  InscrtMltcni  5  first  parunieter  has  the 
same  fnrmat  as  an  entry  in  a  (nenu/item  line  list.  It  must  be  followed  by  a  null 
eharacter       or  a  return  diiiracter  {13). 

You  can  also  delete  items  from  a  menu.  For  this,  use  DelcteMItcm; 

PuahWord  #343  ;ID  of    item  to  be  deleted 

.DeleteMIlcm 

You  should  not  iisf  DeleteMltem  as  a  snti^titutf  for  DisablcMlleni. 

After  you  ha\'e  used  the  InsertMItem  nr  Dele te\)Iteiii  functions,  the  vortical 
size  of  the  menu  tiecessimb  will  have  ehanjued,  an  tall  CalcMenuSize  as  you  would 
■iftcr  using:  SetMItem  to  thanse  an  item  name. 

Checldnj^  and  Marking 

You  (.an  tbeck  or  uncheck  a  menu  item  using  ihe  CheekMltem  timctiun: 

True         GEQU  JSODO 

PuahWord  #True  ^Triie  -  ctieck  it 

PushWord  #277  ;ilem  ID  rLimber 

Checlrnl  tern 
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The  first  parameter  pushed  on  the  slack  is  a  Boolean  instruction  indic-ating  whether 
a  check  inarlt  (ASCII  code  18)  is  to  appear  to  the  left  of  the  item  name  [true)  or 
whether  it  sliiiuld  not  appear  (fiiJsc].  This  example  i^hccVs  item  277  because  the 
Bmilean  parameter  is  true.  Push  a  value  ofO  if  you  want  to  uncheck  the  item. 

You  can  place  any  character  ycju  like  to  the  left  of  the  item  name  using  the 
SetMItemMarlc  function.  Here  huw  to  use  a  diamond  character  as  tht  marking 
character:: 


PushUord  #*13  ;ftSClI  code  for  "diamord" 

PuahWord  #333  ;itern   ID  nLimher 

_5*tMlteniMarfc 


H^ere  are  the  codes  far  the  ftmr  special  icons  included  in  the  system  font: 


17  open-apple  icon 

IS  cheekmark  icon 

19  diamci'nd  icon 

20  solid-apple  icon 


If  you  want  to  remove  the  marking  character,  specify  au  ASCII  code  of  0  ibr  the 
marking  character.  To  determine  which  character  is  currently  marking  aii  item,  use 
GetMItemMark; 


PushWord  #0  japace  for  result 
PuahWohd  #333  ID  number 

_Ge tMf  t  emPlar  I: 

PLfl  ^Ffesult  CDntairs  character  codi 


If  the  item  specified  is  nut  marked,  the  result  is  0. 


Changing  the  Test  Style 

Item  names  can  be  drawn  in  plain  ttxt  or  tfiey  can  be  boldfaced,  italicized,  under- 
lined, outlined,  or  shadowed.  Select  a  text  style  by  passing  a  style  word  to  Set- 
MltemStyle  as  follows: 


PushWord  #1:0 QOOOOOI  ;stylE  word  (bold) 

PushWor-d  #267  jiltm   lU  tiumber 

_SetMItemStyle 
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Five  bits  in  the  Style  word  cDsble  the  five  fundamental  style  attributes: 

bit  0  bold 
bit  I  italic 
bit  2  underline 
bil  3  outbne 
bit  4  shadow 
tit  5-1-5  zero 

To  select  a  piirticular  style,  set  the  appropriate  bit  to  1.  The  style  types  are  not 
mulually  exclusive,  so  you  caii  tombine  them  as  you  like.  Use  a  style  word  of  0  if 
ynu  the  item  name  drawn  in  plain  text. 

•  \'ote:  Early  versions  of  QuickDraw  do  not  support  italic,  oudine,  nr  shadow. 
In  addition,  fcmls  with  a  descent  of  0  and  1  cannot  he  underlined;  this  includes 
the  default  system  font  used  on  ihe  Gs. 

To  determine  the  current  style  of  an  item,  use  GetMIteniStyle: 

PushWord  #0  ispace  for  result 

PuahWord  #E67  ;ilem   ID  number 

_GfttMI temStyle 

PLfi  ;pop   tfit  result         atyle  word) 

The  result  is  a  style  word. 
REMOVING  MENUS 

Til  remove  a  menu  definition  from  the  system  permanently,  thus  freeing  up  the 
memory  it  uses,  first  lemovi?  il  from  the  system  menu  bar  with  DeleteMenu: 

PHA  ;3pflce  for  result  (handle) 

PushWord  Menu3D  ;10  number  of  menu 

_GetMHaridle 

_Deletenenu 

Nntite  that  GetMHandle  is  used  herp  tn  determine  the  handle  tn  the  system  menu. 
Of  euurse.  if  you  saved  the  handle  returned  by  NewMenu.  you  could  just  call 
Delete.\ieiiu  alter  pushing  the  handle  on  the  stack. 
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Next,  tall  DisiwseMenu  (this  code  assumes  fhat  ynu  have  saved  the  inenii  handle 
at  MemiHiidl): 

Pu a hLo ng  MenyHnd ]  ;Heiidie   to  menii 

OntJt!  y<iii  have  rlispnsfd  of  a  menu  lik(?  this.  yt>u  cannnt  use  it  u;^m  unless  you 
redefine  it  with  XcwSk^nu. 

Tu  reinjitdl  a  mc-nu  that  was  removed  with  L>eleteMenu  but  that  was  not  disposed 
ot.  ii.se  till"  Injst'rtMtMiL  fuiictitm  deserilfifd  t'dxlier  in  ihis  ehapter. 

NuIl-  that  neither  Di.spose.Menu  nur  DeU-teMenu  lias  a[i  iuimediiLte  efTecl  Dn  the 
appeanlnet  nf  the  nw.?ni]  har  lin  the  SLTe^en.  To  redraw  llie  [iieiiu  bar  without  the 
rejiioveJ  inenu^  call  FixVlenuBai"  lu  reL-akulate  the  menu  bar  size,  then  call 
DrawMenuBar. 

USER  INTER.ACTION 

A  vital  part  uf  any  pni^ram  u^ing  menus  is  the  eude  that  handles  aeti\ity  in  the 
menu  har  area  in  a  iJianner  eiinsiatent  wilfi  Apple  s  u^e^-interfaee  ^uitletine!!.  There 
are  IwiJ  j^eneral  wayi  nf  duinfj  thift,  dependinf;  iin  whether  yoU  are  USinfi  a  TaskMaAter 
event  loop  ur  a  CetNextEvent  event  loop. 

Usin^  CielNextEvcnt 

Handling  menu  bar  activity  if  ynu  arc  uiiin^  GetXcxtEvenl  requires  the  most  work. 
T]ie  prnfjram  in  listing  7—3  shuws  what  tn  dn.  When  (CetNextEvent  returns  a  mouse- 
down event  (Lode  IK  it  calls  iMndWindow  tu  determine  if  the  event  (K-eurred  in  the 
menu  bar  area.  If  it  did,  I'indU'indow  returns  a  result  ol  wlnMeuuBar  {17)  and  the 
proBrani  talh  MenuSelect, 

MenitSelect  traeks  the  movenient  of  the  mouse  until  the  mouse  Inilton  is  released. 
It  manages  all  llie  pull-down  menu  chores.  Ineludirif;  liinhlijtlitiiig  appropriate  menu 
titles  and  item  names.  It  returns  a  result  indicating  which  menu  item  was  selected, 
if  any. 

Ilere  is  the  tailing  sequenc'e  for  MenuSelect: 

PuitiPlr  TflskPiccoi'd         iPointer   tc  laali  record 
PyahLcng  #0  ;0   -   sysLeim  menu  bar 

_Me  nu 5e 1 t 

The  task  record  used  by  this  eall  is  the  CetNextEvent  event  record  that  returned 
the  mouse-down  event,  followed  by  the  long-word  TaskDala  and  TaskVlask  fields. 
MpnuSelecf  retuniJi  ils  result  in  ihi'  Ta.skDala  field:  the  low-order  word  is  the  ID 
of  the  menu  item  selected,  and  tlie  liigli-OTder  word  is  ihe  ID  of  the  menu  selected, 
(TaskMask  is  actually  used  by  Ta.skMaster  only,  I  The  program  can  then  lake  whatever 
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action  is  appropriate  for  the  menu  item  selected   if  the  result  is  0,  no  menu  item 

was  selcclcd- 

The  pmt!rarn  in  listing  7-3  also  tlipcks  fur  keyhoard  equivalents  iil  menu  items. 
As  was  mentioned  earlier  in  this  ihapter,  an  item  can  be  iissiiciated  with  a  keyboard 
equivalent  u^infi  the  *  spetia!  (.-hariicter  To  select  sQth  a  menu  ileni,  you  just  tap 
the  appropriate-  kc\  while  hnldiiig  doviii  the  Open-Apple  k*-y. 

To  deal  with  kt.'yboard  equivalents,  the  pn^gram  ehet-ks  for  key-dowii  and  autokt-y 
events  When  it  finds  oiip  of  these  cventn.  it  passes  the  TaskRecord  to  MenuKey 
for  analysis.  MenuKev,  like  MenuSck'ct.  rt.turns  the  ID  ofthe  menu  item  seleetetl 
in  the  low-order  word  of  the  TaskData  field.  Il  the  keystroke  did  not  tnjrre>p(ind  to 
the  primary'  ur  alternate  equivalent.  McnuKeV  returns  an  ID  of  0. 

Using  TaskMaster 

It  is  much  easier  tn  deal  with  activity  in  the  meini  bar  nsinj;  TiwkMiLster  than  it 
usinR  GetNextEvent,  Ijttauie  TaakMasler  aislojnatitally  ealls  FindWindnw  and 
MeniiSeleet  to  delermine  what  menu  item  was  selected.  It  also  eall^i  MenuKey  to 
cheek  for  keyboard  eipiivalents.  All  yon  liave  in  do  is  make  Jiure  thiit  n]enu-bar 
hm^dling  has  been  enabled  in  the  TaskMask,  The  program  in  listing  7—1  allows  what 
a  Ta.skMaster  menu-handling  routine  looks  like. 

The  event  eode  returned  by  TaskMaster  when  a  menu  item  has  been  selected  is 
wlnMcnuBar  (17).  This  is  the  same  cfidc  returned  by  FmdWintlow  for  a  innuse- 
down  trvcnt  in  the  menu  bar.  The  ID  ninnhers  of  the  seleeted  menu  and  menu  item 
arc  stored  in  the  high-  and  low-order  words  of  the  TaskData  field  oJ'tlie  Task  Heboi  d, 
respectively. 

Generally  speaking,  TaskMaster  simply  return;;  the  ID  number  of  the  menn  item 
scleetcd— il  dotii  not  attempt  to  proi^ess  the  selet-tion  in  any  way  {that  i.-i  up  tci  the 
application).  The  exceptions  involve  desk  acucs^iory  itenis.  which  have  menu  [Ds 
fironi  1  to  249.  and  special  menu  items,  which  have  IDs  from  2.5n  to  SiiS. 

If  a  desk  aeces.snry  itctn  is  selected.  TaskVlaater  aiitninatieally  opens  the  desk 
accessory  in  Ljuestion  and  returns  a  null  resnh.  Il  a  desk  aece.'isary  vviiidiiw  is  attive. 
&]jecial  menu  items  arc  processed  liy  passinjj  ihein  tn  the  desk  acee_ssor)'  for  actinn. 
The  desk  act"es:anry  handles  the  t:lfise  item  (#2551  by  closing  its  window.  Editing 
items  (#2.51)  to  #2.54)  may  or  may  nut  he  handled  b\  the  accessory  (see  chapter  9); 
if  they  are  not,  TaskMa.stcr  returni  a  wlnSpedal  (25)  event  c-otle  to  pve  the  appli- 
cation a  chance  lo  do  smm'lhini;  with  it, 

Removing  Menu  Title  Hi|;!hhj;htLiig 

If  the  user  .selects  a  menu  item,  both  MeiniSeleet  and  MeiuiKey  hif-hllsht  the  title 
of  the  menu  in  whicli  it  appears.  When  proeessinn  nf  the  Liinmiiintls  ends,  you 
sh<iuJd  eall  HiiileM l  iui  to  return  the  title  to  its  nnrnial  appearance: 
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Pii'shUford  #'0 
PjahWord  TaakDatfl+2 
„H 1 1 1 t*rtefm 


;  0  =  Tiorma  1  title 
1  Menu    I D  number 


The  first  parameter  is  a  Bouleaii  parameter  iiiidicatin^  whether  the  menu  title  is 
to  be  highlijilited  (true)  or  drawn  nomially  Uiilsf).  The  vatue  passed  here  is  falsf 
(0),  sci  the  title  is  r«?iirawn  nnrmiilly.  The  second  parameter  is  the  ID  number 
of  the  menu,  it  is  stored  in  the  high-order  word  of  the  TaskData  field  of  iJie  event 

record, 

COLOR  AND  THE  MENU  MANAGER 

By  default,  menu  hars  and  pull-down  menus  are  white  and  any  text  items  inside 
them  are  hlack.  Tlie  menu  bar  uuthni:.  menu  outline,  underlines,  iind  dividing  lines 
are  also  hlaek  When  items  are  highlijrhted,  the  text  betomes  white  and  the  back- 
ground black. 

With  the  SctBarColors  function  you  can  change  the  colors  the  Menu  Manager 
uses  to  display  menu  bars,  menus,  and  the  text  items  in  them  The  colors  used  for 
nnseletied  items,  selcfted  items,  and  outbncs  can  be  set  separatf?ly. 

Here  is  how  to  call  SetBarCulors: 


PushUoF^  d  NeuBarCo  1  OF 
Pu5hUlord  NewInvertColor 
PushWord  NewOutCclor 
.SetBarColors 


VSPttctfd  cclor 
^out I ine  color 


Each  of  the  three  parameters  defines  the  colors  oi'two  areas,  as  follows: 


1»AHAMETEH 

NewBarC'olor 

NewInvertColor 
NewOutColor 


BITS  0-3 

Text  t-'oiur  when 
itejn  is  nut  s<"- 
leetetl 

Text  color  when 
item  is  selected 
I zero] 


BITS  4-7 

Background  color  when  item  is  not  selected 

Background  color  when  item  is  selected 

('(ilor  of  outline  of  menu  and  menu  bar. 
underlines,  and  dividing  lines 


Bits  8-15  must  always  be  l>,  unless  you  specify  a  liegative  parameter  (bit  15  -  1). 
When  a  parameter  is  negative,  the  color  scheme  of  u  Riven  attribute  does  not 
change. 

In  f>40-by-2oa  mode  ynu  can  use  eoEor  nuniliers  from  0  to  '3.  in  320-hy-2(K)  mode, 
you  can  use  color  numbers  from  0  to  15.  The  standard  colors  assigned  to  each 
number  were  given  in  table  6-1  in  chapter  6. 
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Table  R7-1j    The  Major  Finicdnns  in  iht-  Menu 

Miiiiaijf^r  Tunl  Srt  fffiOFi 

Funetion 

Stack 

UeScVlTfllOTv  Uj 

Function  N'oric 

Number 

Parameters 

Parameter 

Calf  Mejiu  Size 

$1C 

NewWidth  (W) 

Menu  width  (0= automatic) 

XewHfjj^ht  (W) 

Menu  height  (0= automatic) 

NlcnuID  (W) 

ID  iif  jnenu 

CheckMItem 

Chfckltcm  (W) 

True  -  check/False  - 

uiiLheck 

ItrnilD  (W) 

ID  of  jiienu  item 

Del  eteM  Item 

SIO 

ItcmlC  (W) 

ID  of  menu  item  to  delete 

Delete  Menu 

$0E 

McmilD  [W) 

ID  of  menu  lo  delete 

Disable  MI  tem 

$31 

lteniID{W) 

ID  of  men II  item  to  disable 

DisposeMenu 

$££ 

MeiiuHaiidlc  iD 

Handle  to  menu  to  dispose 

DrawMenuBar 

$2A 

[nw  parameters  J 

EnableMItcni 

S30 

It^fln]D  (W) 

IIJ  cji  inenii  itetfi  to  delete 

Fix.MertuBai 

result  (W) 

Heiglil  of  menu  har 

GetM  Handle 

*ie 

result  (L) 

Handle  to  meiiiu 

McnurO  (W) 

ID  of  menu 

Get  MI  tem  Mark 

$34 

r<-SL]lt  (W) 

Mark  character  ([>=  no  mark) 

ItemID  (W) 

ID  of  menu  item 

GetMItemStyle 

$36 

resall  (W) 

Text  st>'le 

IteinlD  [W) 

ID  of  menu  item 

HiliteMeiiu 

HilitePkR  (W) 

True- highlight/False -normal 

MenulD  (W) 

]  D  nl  me-jiu 
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Function 

Slack 

Descriptian  of 

Punctioi)  Wofns 

Paramfters 

Parametej~ 

InsertMUcm 

$0F 

AddltcmPlr  [L) 

Ptr  to  itt-m  definition  to  use 

Insert  After  (W) 

ID  of  item  to  insert  after 

MenulD  (W) 

[D  of  tnpnu  to  contain  item 

iTiscrtMemi 

$0D 

AddMeniiHndl  (LI 

Hundli-  tn  inenii  to  insert 

InsertAfter  (W) 

ID  ormeciu  to  insert  after 

Menu  Key 

$09 

TaskRcfPtr  [L) 

Ptr  to  task  retord 

MenuBrirPlr  {U 

Ptr  to  menu  bar  tO=systeni) 

MecuiSclet-'t 

$2B 

TaskReePtr  (L) 

Ptr  tn  task  rccnrd 

ML-miBarPtr  (L) 

Ptr  to  menu  bar  (t>=5ysle[Ti 

Menus  hulDoNv-n 

$03 

[no  parameters] 

Menu  Startup 

$02 

Uw-rlD  [W) 

ID  tAi^  for  int-inyo  allcK-ation 

DPaReAddr  (W) 

Address  of  1  paae  in  liank  0 

NewMenu 

$2D 

n-sull  (L^ 

Handle  to  nipnu  record 

Mf-nuLisl  tU 

Ptr  ti>  menu  list  retojd 

SctBarCoinrs 

S17 

Ni-wBarCnlnr  (\V  ) 

Normal  item  color 

Nt'wInvColnr  (W) 

item  ttilor  when  selected 

NewOutColor  [\VJ 

OuUint^  color 

SefMItfiiiNumc 

NewItpmStr  (L) 

Ptr  Id  new  nieini  item  string 

IbenilDlVV) 

ID  of  menu  item 

Set4MeniiTitle 

Nt-wTilUStr  (L) 

Pti-  to  new  menu  title  string 

Meniiin  (W) 

ID  "f  menu 
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Function.  Stack 
Function  Name      JVuwiJwr  farameUf$ 


Set  M  Item 


$24 


SetMItemMark  $33 


SetMItem  Style  $35 


NewLinePtr  (Q 
ItemlD  (W) 
Markltem  (W) 

ItemlD  {W] 
TextStyle  (W) 
ItemlD  (W) 


Pescriptian  of 
Parameter 


Ptr  to  new  item  ljn€ 

ID  of  itienu  item 

ASCII  cude  for  mark 
character 

ID  of  menu  item 

New  text  style 

ID  of  menu  item 
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Listing  7-1:     A  Siilimiitiiie  fur  Dt-finiiig  Menus  and  a  Metiu  Bar 


•  This   gubroutiTiE    shows  how   Id  defiTit  • 

•  atandard  Apple- F i 1 e -Edi t  menus  ard  a  • 
'  system  me  nil  bar.  * 


START 


Start    defLniTig  the   individual  menus  and  adding  them 
to  the  menu  bar.   This    is   done  ir^m  right    to    le-fl  order 
for  simplicity. 


PuahLong  fQ 
PuBhPl  r  Meni4i-3 
_Ne-wMeiiu 
PushWord  '0 
I  naer  tMenu 


0    =    system  menu  bflir 

P&inter   to  menu  deflfiiliion 

UefiTiE   the  Edit  menu 
Add   to  menu 


PuahLong  *0 
PushPlr  nenul-2 
_N  ewM  enu 
PushWord 
I naer IMenu 


jDeflnt  the  File  menu 


PushLong  'D 
PuShPtr  MeruLI 
_Newr1enkj 
PushWord  #0 
1 naer  tMenu 


;DefiEie  Ihfi  Apple  mer 


PushtJord  '1 

_F  xx'^ppl  eMenu 


jMenLi  ID  (1  =  Apple  menu) 
; ftdd  Dfl^    lb  Apple  menu 


PHft 

_F  1  iMenuBfl  r 
PLA 


;Set   the  menu  alie 


_Drawf1enuBa  r 
RTS 


1 D  L  ap lay  the  menu  bar 


Menu/ i  t  em  1  is  L  a  : 


MeruLI  DC  d        SVHIK'  .H' QD- 

DC  C'"flbout    this  program 


; ftpp 1 e  menu 

.  .  .  ,H'0[J' 


MenuL2  DC  C ' > >     File  \N2',H'0D'      ;File  menu 

DC  C'»'Cloae\N£55V'.H'0D^    i5peci.al  close 

DC  C ' rfrQui l\N257>Qq*  ,H'OD' 


1  tem 
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MetiaL3  DC  C'>     Edit    VN3',H'0D'      jEstit  meTiij 

□  C  C  ■ '*UticJo\N2S0V'Zz  ■  .H'QD'         iSpccial  edit  ilema 

DC  C  ^•^■Cut \N2S1  'Xx'  ,H'  OD' 

DC  C  '  ^/CopyNNSSS'Cc '  ,HiOD' 

DC  Ci»'#Pa5lt\N253*Vtf",HtQD' 

DC  Cf'i'ClEar\N254'  ,H'OD' 

DC  C  *  .  '  ;  End   pf  mPTlij 


END 


Listing  7-2:     Clhangiiig  the  Appearance  of  Items  in  a  Menu  Using  Special 
C'iiaratU'rs 


McnuLI 

DC 

C 

■  >>  At  Ir  ibulea  \N1 ■  ,H ' OD ' 

DC 

C  1 

T^BoldNNSSSB' ,H'OD' 

DC 

C  1 

ta:ic\N2591 ' ,H'CD' 

DC 

CI 

-"UTidarline\N£60U'  .HiQD* 

DC 

C  ' 

#*flU   fittrib<jte5\N261BIU'  ,H'IJD' 

DC 

C  1 

».rDi9ab:it£l\N3G2Di  ,H'ODi 

DC 

C  1 

i-'-VNSeSD^  .H'OD' 

DC 

C  1 

f  Jfinar  li:Ed\N264C  '  ,H'13'  .HfOD' 

DC 

C  1 

"Checked\H?65'  ,H'OD' 

DC 

C  1 

^'■Equiv-alent  B\ N26&' Bb  '  ,  H  '  OD  ' 

DC 

c 

•  *DlyidiTtgV.N2G7Vi  ,  H  '  DD" 

DC 

'^Nora-fll    I  tem\H568<  ,H"  OD' 

DC 

C  ' 

.  '                                    ;  End  of  meTiii 

Listing  7-3: 

Handling  Menu  ActiviW  When  Using  a  GetNextEvent  Event  Loop 

w ] nWeruBa  r 

{^EQU 

17                            J  [  n  mtnu  bar 

STfiRT 

EvlLoop  PHA 

PuahWord  'IFFTF  -.fill  events 

PushPtr  TaafcRec 

_&elNextEvent 


PLA  ;Dld  anything  happen'^ 

BEa  Ek/lLoop  ;No,  5C  branch 

LO"  uihat  ;Get  event  code 

CMP  f^  jnenjie-dQwn? 

BEQ  FindNhere  ;Ve5,   so  branch 

CMP  #3  jKey-do-^n? 

BEQ  EquiwChIc  jVt?,   so  checl  for  equivaltnt 

CMP  *b  ifluto-keyT 

BEQ  EquiuChIc  ;Ve5,    so  branch 
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OoDttier  flNDP 


;    [handle  othtr  types  of  ^went^  hereJ 

BRL  E^/tLoap 
iChecb  for   keyboarct  ^quiualents  of  menu,  items: 


EquwCht       PuahPlr  TaatRcc 
PuahLong  *0 

LDrt  TaskData 
BHE  DoMenLL 


;  0  ■  syalem  menu  bar 
;rnenu   item  selecttd' 


LDA 

BRL 


what 
DaOther 


iGet  code  back 


jTind  out  whtr-e  the  mouse-down  took  place: 


FlndUlhere  PHfl 

PiiShPIr  TheWindow 
PuahLong  where 
_F 1 n  dW 1 nd  QU 
PLA 


;  Space  for  result 

prelum  window  pointer  here 

;pu9h  pairt   Iq  check  (global 

iGel   resuH  code 


CMP 
BEQ 


#w I nMenuHa  r 
■UasMeriu 


; 1 n  menu  bar' 

;  Ves  ,   5 o  Ijr anc h 


j    Ihandle  mouse  activity   in  other  areas  here] 
htil  EvtLoop 


WasMenu         Pu^hPt  r  Tas I Rec 
PushLong  #0 
_MenuSel ec  t 

1    Handl?  menu  selections: 


;G  *  tystern  menu  tiar 
;Determlre  which  menu  item 


DoMenu 


LDfi 
BEQ 

CMP 

sec 


Tas  kDato 
E^/tLoop 

DcMenul 


;&et  menu  Heni  ID 

;Bi"afich   if    nothing  selected 

;l5  it  B  special  item  (ID  <  256)7 
[Vta,   50  branch 


;   This  code  assumt^   that   standard  menu   Items  are  numbered 

i  conseciji  ively  from  2SS. 
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ftSL 
TAX 
JSR 
BRfl 


A 

TitJcQf f 


^a  step  into  table 
;Cail    item    aubrD  ii  t  i,  ne 


DoMerm  1 
TitleOff 


JSR 


DoSpe  c la  1  I 


PushUord  *tl 
PushLJord  TaskData-r^ 
Hi  1  t  teMenu 


;D   ^    title  highlighting  off 
^  The  menLL  ID  la  at  TaahData'S^ 


BRL  EvlLoop 
;  Table  of  subroLitLne  addresses,    in  numeric  order: 


MenuTab 1  a 


DC 
DC 
DC 


I 'Doltem256' 
1  'EdI  te:m257t 
I  'DoIlen^ZSS* 


',  Handle  apecial  editing   items,   close   item  'lerE: 
;    Nnrmally   would   pass    these    lo    the   Deatt  Mflnager 
;  WL  th  Sysl emEd 1 1 . 

DoSpeciai:  I^UUP 


CMP 
BUI 


'255 
D'oEdi  t 


; Close  item' 

;Nd,   so   it  must  be  Edit  ^tem 


;  Put  cade  here  to  close  the  active  window. 

BTS 

;    Here    15    uihere    tn  put    code    to    handle    the    special    edit  items 

;  The   [D.  codei  are  250   tUndo)n   251    (Cut),   2^2  (Copy), 

;  253  <Pa5te>.  and  251  ICi^^r). 


DoEdi I 


SEC 
SBC 
flSL 

JMP 


(EditTeble,*;; 


^Convert    to   0  base 

•x2  to  step    IT' to  table 


Editlable  DC 
DC 
DC 
DC 
DC 


I ' DoUrdo ' 
1 ' DoCul ' 
[ ' DoCopy ' 
I  ■ DoPaa  t  a ' 
I  ■ DoClear ' 
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DoUndo 

flNDP 

DoCiit 

flNDP 

DoCopy 

flNQP 

DoPaste 

fiNOP 

flNQP 

RTS 

TheWlTidow 

DS  1 

;Returned  by  FindMjindoM 

■jGEtNextEuenI    task    r  ecard: 

Ta  s-k  Rec 

flNOP 

i.ii^.  -.  1 

MnB  t 

DS  2 

;Event  code 

Mt5  sage 

D5  4 

;  Euefil   resiil  t 

DS  1 

iTicfca   5L11CE  startup 

DS  4 

sMouae   location  (giohal) 

Hod  I  f  i  e  ra 

DS  2 

;Status  of  modifier  keys 

T  a  s  k  Da  t  a 

DS  4 

;  Ta  5  k  Ma  5 1  er    da  I  g 

To  a  kriaa  fc 

DC              H  ^ I0OOO1 FFF' 

iTaakMaater  handles  all 

END 

Listing  7-4: 

ilniidiing  Mifnu  Activih  Whfii  Using  a  TankMaster  Evt-nt  Loop 

u  I  nMeriuBa  r 

GEQU  17 

;  1  n  menu  bar 

w  I  fiSpec  a  a  I 

GEQU  2S 

;  In  special  mcmj  item 

MenuDemo 

START 

EvtLoop 

PHfl 

PuahWord  'IFFFF 

;flll  events 

PushPtr  TaatSec 

Ta  5  If  Plaster 

PLft 

; &e I  result  code 

CMP                t  TiMicnLiBar 

[Menu    Ltem  aelected? 

B£Q  DoJIenu 

JVC'S,   sa  branch 

CMP  'luInSpecial 

iSpecial   menii  Item"? 

BEQ  DoPlenu 

;Yes,  so  branch 

;   handle  a 

ther   result  codes  here 

BfiL  EutLoop 

;    Handle    metiLl  ^eleclion^; 

DcKenu 

LDA  TaabData 

CMP 
BCC 


Doflenul 


;l5  il  a  special  it  em  {ID  <  256)7 
;Ye«^    so  branch 
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;  This  code  aaaumes  that  standard  menu  items  are  numbered 
;  consBcu t Lvc 1 y  from  256, 


AND 

TfiK 
JSfi 
BRA 


A 

[MeruTable.X) 
Tit  leOf f 


sCcnvart  to  0  haae 
;x2  to  step  irto  table 

iCall    Item  BubroLitire 


DaflpTiLi  I 
Ti t leaf f 


JSR 


DoSpec lal [ 


PuShWorcl  »a 
PuahWcrd  Ta^tOata+S 
Hi  I  i  tpMenu 


;0    =    tltie   highlighting  off 
;Thp  mPTiii   ID  15  at  TaskData  +  2 


BRL  £utLoap 
;  Table  of   subroutine  addresses,    m  Tiumeric  order; 


MenuTable  DC 
DC 
DC 


I 'Dollem257' 
[ 'Doltem358' 


;  Handle  special  editing  item^,  close  it  em  he  re: 
Do5peciall  AMOf 


BNE 


DoEdit 


;CIoac  Hem? 

;No ,    9o   it  mu  st  be  Zdit  item 


i  Put   code  here  to  close  the  active  wiTidou». 
RTS 

?   Here   15  where   to  put   code   to  handle  the  apeclal   edit    It  em a 

The    ID  codes  are  ESD    (Undo),    251    (Cut),    252  tCopy), 
1  253  {Paste),  and  25'1  (Clear). 


DoEdit 


SEC 
BBC 

TAX 
JI1P 


(Edi (Table, X ) 


jCoTivert   to  0  base 
jjt2  to  step   into  table 


EdlitTahle  DC 
DC 
DC 
DC 

uc 


1  'DoUndo' 
I  '  DoCiit ' 
I  1 DoCopy ' 
I  'DoPaslef 
I  'DoClear ' 


Reference  Scclion  265 


DoCuI  flNOP 
DoCopy  ANOP 
DoPaate  flNOP 
DoClear  ANDP 
RTS 

;TaatMa5ter    ta^k  record: 


flHDP 

D5 

message 

When 

D3 

DS 

■( 

Mod  L  f  1  Bf s 

D5 

DS 

4 

DC 

14 

I  tODOOIFFF' 


END 


;Event  code 

; Event  result 

;Tick5  since  startup 

^Pl^use   locatic-n  (global) 

;Slatu9  of  modifier  keys 

iToskMaater  dais 

^TaskMaster  tisndiea  all 
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CHAPTER  8 


Using  Dieilog 
and  Alert  Boxes 


Apple's  staiidiirtl  iiser-in(frl'iK-f  Riikk-liiit'S  desmbe  Iwii  speiiiil  types  uf  viintii)v.'> 
Ciilk'i!  (Uiiloa  boxes  and  <iiert  hoxa.  Tlit-  eeiieral  appearaiit-e  of  these  lypes  ol 
wijiduws  is  shown  in  Hj^ures  S-1  and  S-2.  Didilij^  Imxcs  art-  conve:itiijnally  ust'd  tu 
rc(|iic*;t  certain  type's  ol"  input  fmm  llie  usfr.  Tlity  uui  include  several  data  input 
fields,  cnntaiiiitig  SlilIi  ilenis  ds  li  line  ol  lext  that  be  eJiled,  Llietk  luwuis. 

buttons,  and  stroll  controls.  They  can  also  TOotain  static  items  which  Liinnol  be 
mddific-d.  ^iuth  ii:s  tcNl  strings,  icon.s.  and  pictures. 

An  ilk  rt  Iww.  ii.s  its  name  suggests,  iiornialk  Wbirtis  a  user  ol  the  consequences  of 
a  proposed  action  v^liich  mi^ht  result  in  the  destruction  or  loss  ol  data.  In  a  typical 
application,  an  alert  box  wiitains  "OK"  and  ■■Cancel  "  buttons  thjt  can  be  clicked  to 
eitlier  vrriK-  the  action  or  abort  it  For  instanct',  if  you  are  runiung  a  disk  ntilit\ 
program  and  you  try  to  format  a  disk,  you  will  invariably  see  an  alert  box  warning 
you  that  the  oprriitioin  will  destroy  data  and  asking  you  to  verify'  that  you  wish  to 
proceed. 

Alert  htjuei  can  be  uNcd  to  dtsplny  status  information  as  well.  Most  "AlioiH... ' 
items  in  tlie  staniJarcl  Applp  iiipoli  iisr  alert  boxi's  to  display  authorship  and  copyright 
inlurmation.  for  c'xaniplc. 

The  main  difference  between  alerts  and  diaJogi^  is  that  alerts  do  not  contain  any 
user-alterable  input  rii  eas,  .^uch  as  a  text  editing  box.  Thcry  contain  only  .static  items 
lUid  one  ur  niDre  buttons  you  can  click  to  dibnii^s  the  aicrt  and  continue  with  the 
main  ilpplieatioii. 

To  create  and  eoiitnil  dialotl  and  alert  boxes!,  vnii  must  use  a  tool  \tit  called  tbe 
Dialu^  Miina^er  (tool  set  2,1).  This  chapter  inveKtigatt^s  the  Dialog  Manager  and 
explains  hmv  you  can  use  it  in  your  applications. 
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Figure  8-1,    A  Dialog  Bo?t 


Dofiiniunications  Parameters 
Baud  Rate:  03DD     (§)12Dff  O2N0D 
Data  Bits:   ®B  O? 
Stop  Bits:   (fil  O2 
Parity:      (fiHone    OEven  OOdd 
□  Filter      EXON/XOFF   □  Line  Delay 

Download  File: 


Messages 


DK 


Figure  8-2.     An  Alert  Box 


/j\   Do  you  want  to  erase  PROGRflH.BflS? 


Concel 


STABTING  UP  THE  DIALOG  MANAGER 

Ta  start  up  ihv.  Dialns£  MaiiaRcr,  pass  tlif  ID  of  the  pn)Rrain  (the  one  returned  by 
MMStarlup)  to  DjalogStartup^ 

PushWord  MylD  iProgram  SD 

_Di.alogStartup 
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Calling  Dia]ogSlartui5  prfparcs  (he  Dialog  Manager  for  activity  and  initializes  all 

interna!  variabR'^i  and  riiiitint's. 

Beuaime  the  Dialog  Manager  uses  QnicbDraw  II.  the  Window  Manager,  the 
Vlt-mi  Maiiagcr,  the  Control  Manager,  aiifJ  r^e  l.incEdit  tool  sets,  you  mvist  start 
them  iip  Hrfore  calling  DiaUigStartiip.  The  STANDARD. ASM  piogram  in  chapter 
3  takes  cart"  of  (his  ft>r  yiiii. 

The  only  tool  set  in  this  list  that  has  nut  been  diNcussecl  before  is  LineEdit,  a 
tool  set  used  i'or  editing  lines  of  text.  Tt>  itart  it  up,  you  must  provide  one  page  in 
bank  $00  that  it  tan  use  as  a.  diretl  page,  Here  is  ibe  sttirt-up  seQLie]iee: 

PushWord  MylD  nPfogramlD 

Pu^hUord  DPSpace  ^Rddres^  of  one  page  DP  area 

_LES,lar  lup 

The  standard  LmeEdit  editing  commands  will  be  examined  later  in  this  chapter. 

When  vfHi  hitve  finished  using  (he  Dialoij  Manager,  shut  it  down  with  the 
Dialogs  hut  Down  riuictiiin.  This  function  expetts  no  input  parameters  mid  returns 
no  resuUs.  You  can  shut  down  LineEdtt  by  catling  LEShutDowu  in  the  same  way, 

CREATING  DIALOC  BOXES 

Two  general  elasses  iif  dialog  biixc-s  can  he  jniplemciUcd  gn  the  CS:  mfjdal  and 
modt-lpss.  A  mndal  dialog  hqx  is  nnc  that,  nncc  displayed,  handles  all  keyboard  and 
mouse  events  untd  the  iisiT  di>;misses  the  h<iK  hy  tliekini;  a  button  in  the  biix. 
Mouse  clicks  outside  the  dialog  box  are  ignored,  so  you  cannot  pull  down  a  menu, 
select  another  wiDdow,  ar  use  a  desk  acecssory  until  the  modal  dialog  box  is 
dismissed.  In  fact,  this  is  how  the  mcxlal  dialog  Ikjx  Rets  i(s  name;  when  you  are 
using  it,  you  are  eOnhned  tD  a  ^pecidl  operating  mode  until  ii  butttm  is  elieked. 

A  modi'li'ss  dialog  hnx,  on  the  other  hand,  is  just  like  any  other  window  on  the 
StTt-en,  and  TaskMastcr  treats  it  as  siic-h.  Il  has  a  goaway  Imx  and  a  title  bar,  but  no 
zoom  bos.  grttw  box,  or  scroll  i-ontrols.  The  user  is  free  to  switch  between  the 
modeless  dialog  box  and  any  other  window  on  the  screen  in  the  usual  way-  You  can 
remov  e  a  modeless  dialog  bii\  fr<jm  the  screen  ju^it  as  you  ■would  any  rrther  window: 
by  clicking  its  goaway  box  ur  selecting  the  Close  item  from  a  File  menu  when  the 
windtjw  active. 

Modal  and  modeless  dialof;  boxes  are  defined  and  created  u^infj  the  same  General 
programniiiiK  tecbiii(|ues.  "Hie  difieretice  in  their  behavior  arises  beeduse  ditferenl 
iiiAtruelions  are  used  to  interact  with  tbem  while  they  are  on  the  screen. 

Modfd  Dialog  Boxes 

Tu  create  a  modal  disilog  hii\.  you  can  o^e  either  \eu'\|ndalDialog  or  GetNew- 
ModalDialog.  The  main  dilferencc  between  the  two  i?;  that  ;dl  the  parameters  for  a 
NewModalDialog  call  are  pushed  on  the  stack.  With  GetNewModal Dialog,  the  only 


3,araiiii-ter  is  ii  pomt^T  to  a  dialog  tt.mpK.te;  the  template  contain,  all  the  infnrmalion 
needed  lu  rli-^plav  the  dmlo^  Iwjx  Lwreclly, 

You  will  pruhahly  pr<  f.r  to  use  GaNcwModulDiabg,  Wi^use  .t  requires  less 

work,  Here  is  how  (o  call  it: 

PHA  ;5pace  for   result  [long) 

PH  A 

PualiPtr  DUgTejTip  iPoirter    f  dialog  tempUle 

Ge  I  NewModfl 1 D la 1 og 
PopLong  DialogPtr  \Pop  dialcg  pointer 

An  example  nf  hew  to  usi'  GetNewModalDidoK  is  shown  in  listing  8-1.  It  treates 
the  (UaU>n  bfJX  sliown  ill  Figure  S-l,  .     .  n 

Gc-tNewMnaalnialog  dr=i^s  the  dialuK  box  o,i  the  sm-.^n.  bn  does  not  actually 
draw  the  items  inside  tlK'  \:ox  [tha!  is  dtme  by  XSndalUial-f!.  see  bebw).  Th^  ^^^^^^^ 
returned  bv  CelN.^wModalDishJK  is  pointer  to  the  internal  reeonl  that  the  Dialog 
Miul^gi^T  maintains  in  order  tn  keep  track  of  the  modal  dialog  Save  it  for  use 
with  other  dialog- Tela  led  iuiie!i«>ns.  ■  .  i  i 

Jhv  diuloj;  leriipkte  required  by  KetNewModulDialny  is  a  viable  length  labU' 
c-ontamins  inf..r<natK.n  abuul  the  size  of  the  diJog  hox  and  the  items  it  i.  to  tamtam. 
Here  is  its  structure: 

^  DC  ]'t,l.b.r'  ;Corlent   rectangle  (global) 

DC  I'JFFTF'  -.Nuri-zero  =  Visible 

H'O'  jReference  constant 

DC  Mi[teml'  iPointer   to   Ist    item  template 

nc  MMtem?'  iPointef  to  2nd  item  template 

Dc'  MMttmN'      ;PoiTiter    to  N  t  ti    Llem  te^riplate 

[jQ  I^I'Q'  ;Long   z^fo  lermiTiator 

The  tempUkte  becins  with  the  reetansular  dimensions  uf  the  cotilent  portion  of  the 
dialoB  box,  \n  global  enordinates,  These  dimensions  are  followed  by  a  Boolean  va  ue 
that  indical..  whether  nul  th.  dialog  box  i.  to  he  visible;  you  shonld  ui.k.  this 
value  non-zero  (true)  iu  that  the  box  will  appear  uu  the  .eret-n.  The  third  parameter 
i!.  a  refereno^  constant  that  the  applieatiaii  can  use  fur  anythms  :t  likes. 

Ne-ct  coim  s  a  series  of  pointer,  to  the  templates  for  the  various  items  ta  be  drawn 
i,..ide  the  dialog  bn..  These  item  templates  will  h-  discns.ed  in  the  section. 
The  last  item  pointer  is  rolluwed  by  a  long  zer«.  whieli  mark;,  the  e-nd  (if  Uie  list. 

Il  vuu  ehocise  to  use  NewModalDialoK.  ynu  must  pruvide  three  input  parameters: 
a  pointer  In  the  ...ntent  rcetangle,  the  visibte  H.^.  and  thc^  reference  constant: 

PHA  1  Space    for  result 

PiishPtr   BgundsPect  jPointer    to   rectangle  dct 
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_Newr^oda  ]  Dia  1  og 
PopLorig  DialogPtr 
RTS 


]VlSlblp    Bdol ean 

; Reference  constant 

;  Pop   dialog  pointer 


BoiindsRect   DC    lM,l,b,r'  ;IRectaTigle  dtfinition 

Notiic  thiit  thf  itfiil  dt-finitinnis  jrc-  illiSf^liiK.  Alter  i:iilini;  NowModali^ialog,  you 
must  attai-h  items  tn  Hii'  (liak>i;  rt'uord  iisiiin  ihi"  NL-wUlteiii  or  GftNf  wDltem 
fumtinns.  Buth  are  described  lattr  in  this  thaptcr. 

ITEM  TYPES 

As  mentioned  ahovo.  thr  liiitlon  tcnipkU'  vxhi  piisij  to  GelNewModalDialiip  ttiutalns 
painters  lii  tlie  definition  templates  for  t-ac-h  item  thai  is  to  apprar  in  the  dialog  l)ox. 
Tlie  ilL'iiis  supported  hy  the  Uialu^  Mana^Ier  are  as  foUnws: 

■  Butlon 

■  Chctk  hnn 

«  RiidLu  button 

■  SltqII  bar 

■  Uscr-de fined  control  (two  tyiJPs) 

•  Static  text  (up  tu  255  characters) 

•  Lung  static  text  I, up  to  32,767  tWacters) 

•  Editable  line 

■  Icun 

"  QuickUriiw  II  pieture 

•  User-defined  item 


Tlie  standard  :iyinl>*ilif  names  tor  thrsp  items  are  shown  in  table  FiRure  8-3 

shows  what  the  standard  item  types  li3ok  like. 

The  template  ft»r  any  item  has  th*"  kill^^wing  struLture: 


1 1 emTemp 


DC 
DC 
DC 
DC 

DC 


14' t  ,  1  ,b.r ' 
I  '  3  temType ' 
11 ' 1 lemDescr ' 
I  >  ItemValiie' 


Unique    ID  code  for    the  item 
The   1 1 em  rec  tang  1 e 
[  lem  type  code 

Item  descriptor  (item  apecifjcl 
Initial  value  of  item 
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Table  8-1:     Ittin  Type  Cncies  i.ir  Dialog  audi  Alt^rt  Buxes 


Code 

Descfiptinn 

Bultnnlt«m 

$[«0A 

Buttim  toiilro] 

Checkllem 

StfflOB 

Check  box  control 

Radiultein 

SOOOC 

H^dio  button  item 

StrollBarl  iem 

StOOOD 

Scroll  bar  control 

UserClIItein 

$000E 

User-defined  control 

$O0OF 

StiLtie  text 

LongStatText 

SOOlO 

Long  static  text 

EditLine 

$0011 

Editable  line 

Icon  Item 

Icon 

Picltem 

S0013 

QuickDraw  II  picture 

Uscrltem 

SOOU 

User-defined  item 

UscrCtlRem2 

80015 

User-defined  control 

ItemDisabJt 

$8000 

Add  this  to  disable 

NOTE;  Add  llai.'  Li^nila^l  IteraDiiablie  to  thf  li>de  for  an  item  la  iliuliie  llial  item. 


DC  1  '  1 1 emFlag  '  iDisplay  flags    [item  specific) 

DC  14 1  I temColor '        ^Pointer    ta   Hem's   color  table 

The  ItenilD  is  an  idcntififatioTi  iiundicr  you  assign  to  the  iiFm-  Nu  other  item  in 
the  dibilog  bo\  may  ust  the  wiine  number. 

IteinKecl  is  the  rectangle  in  which  the  item  will  be  drawn.  Tke  t-oordinates  are 
in  standard  top,  left,  buttoni.  right  (irder.  You  will  find  that  the  inost  frustratini^ 
aspect  of  defining  an  item  is  adjustini^!  its  rectangle  *o  that  it  appears  in  the  correct 
position  and  d"cs  not  overlap  other  items. 

ItemType  i*;  the  code  the  Diakitf  Manis^^r  uses  to  idcntifv  the  type  of  cnntrol 
you  are  defining.  The  values  for  eaL-h  type  of  item  are  shown  in  table  S-2.  The 
svinbotic  names  for  these  codes  are  defined  in  the  STANUAKD.ASM  file  with 
GEQU  dir£'ctive,s, 

The  meaning  of  ItemDescr  is  diiFerent  for  each  item  type.  It  is  generally  a  pointer 
to  a  data  4rea  associated  with  the  item.  For  a  static  test  item,  for  example,  it  points 
to  the  text  string. 
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Figure  f^'li.     Cnmninn  Irpm^  Used  in  DialnE"  Boxes 


Editable  Text 


□  Check  Box  Off 

® Radio  Button  On 

^Icon    O  Radio  Button  Off 

Scroll  Bar--) 


ItemValue  (Contains  the  initial  value  ol  th*?  item.  As  wi\]  dist:us?st'd,  tnnlrol 
items  like  check  boxes,  radio  huthins,  and  scroll  bars  have  values  associated  with 
them, 

The  primary  purpose  of  IteiiiFlag  is  to  indicale  whether  the  item  is  to  be  visible 
or  invisible.  For  visible  items,  bit  7  must  be  0;  for  invisible  items,  bit  7  must  be  1, 
Certain  other  items,  namely  hnttons  and  scroll  b:ir^,  nse  other  hits  in  IteniFlag  to 
control  their  appearance.  Radio  buttons  nse  sis  bits  as  a  family  number  so  that 
related  radin  buttons  can  hv  dpalt  with  as  a  s^mp. 

IteniCtdur  points  to  a  color  tabic  for  the  item.  Set  it  to  0  to  use  the  standiird 
culor  table. 

Each  of  (he  item  types  supported  by  the  Dialog  Manager  is  destrihed  be^ltfw. 


Buttons 

A  button  item  (ButloiiUem)  is  a  rcLtaiiRlc  tliat  the  user  can  click  to  dismiss  the 
dialog  box.  The  application  should  react  to  tlie  click  by  saving  the  values  of  any 
other  items  in  the  dialog  box,  removing  Lhe  bos  from  the  screen,  and  then  taking 
whiitever  iiction  is  appropriate  for  the  button  selected. 

The  ItemDcscr  field  in  an  item  template  i>oints  to  die  name  of  the  button 
(preeeded  by  a  length  bvtej;  the  name  is  drawn  inside  the  button  rcetanjjle. 
ItemValue  is  not  used. 
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Table  S-2;    The  Contents  of  the  JtcmDescT,  Item  Value,  and  ItemFlag  Fields  in 
ati  Item  Template 


Item  Tijpc 

ItemDescr 

IteiriValue 

Buttonltem 

Pointer  to  ICeni  name 

[iNot  uficd] 

Chctkl  tern 

Pointer  to  item  name 

O=off.  l=on 

Radiol  teni 

Pointer  to  item  name 

0-off,  l=op 

ScroilHaritem 

Painter  to  action  procedure 

Initial  value:  0  to  290 

UserCtlltem 

Pointer  to  control  procedure 

Initial  value 

SlatText 

Pointer  to  statit  string 

[Not  used] 

LongStatText 

Pointer  to  text 

Text  len^h:  0  to  32767 

EditLine 

Pointer  to  default  string 

Maximum  length;  0  to  25.5 

Icon  I  tern 

Handle  to  icon  definition 

[Not  used] 

Picitem 

Handle  to  picture 

[Not  used] 

tj  sprite  m 

Pointer  to  definition  prfx;edurc        [Not  used] 

UserCtlItem2 

Pointer  to  eontrol  parameters 

Initial  value 

Item  Type 

ItemFlag 

Butttinltem 

Bit  0  :  J  = 
Bit  I  :  1  = 

bold  outline,  0  =  normal 
squaj^-corner,  0  =  round-corner 

Radiol  tern 

Bits  0-6  :  fa 

inily  number  [0  to  127) 

Scroll  Barltem 

Bit  0  ■  1  = 
Bit  1  :  1  = 
Bit  2  :  1  - 

up  arrow  on  scroll  biir 
down  iirruw  on  scroll  bar 
left  iirruw  on  scroll  bar 

Bit  3:1  =  right  arrow  on  scroll  bar 

Bit  4  ;  1  =  Knrizontai  scroll  b*r,  0  =  vertical 

\aTt:  For  nil  otiier  jlcrrs,  i^t  bit  7  of  JtemFk^  to  1  la  maici.-  iKl-  item  mvi-iib|<< 

The  button  is  usually  a  rounded-corner  rectaagle,  hut  it  can  also  be  a  square- 
Lorneretl  rectangle  with  a  drop  jihadow  if  bit  I  of  HemFIag;  is  set  to  1. 

Most  modal  dialog  hones  and  alert  boxes  contain  ;U  len^t  one  button  so  that  they 
can  bf  dismissed  in  accordance  with  the  user- interface  guidelines, 

A  default  button  one  which  may  be  selected  by  pressing  the  Return  key.  By 
convention,  the  default  button  is  enclosed  by  a  dark,  black  border  so  that  it  can  be 


274    Uning  Dialog  andAiert  Boxes 


readily  identifiea.  If  ynu  define  mure  than  one  button  in  a  dialu^  box,  the  one  most 
likely  to  be  selected  should  U-  made  the  delaidt  su  it  can  be  selected  easily  from 
the  kei'hoard, 

For  nKidid  diJilog  boxes,  a  Buttonltcm  with  an  ID  nf  1  is  always  the  default  item. 
5iiLh  a  buttun  is  typi^-ally  labdtd  as  the  OK  biittmi,  Fot  aleit  box«,  a  l>i]ttnn  with 
an  ID  of  either  1  OT  2  in  the  item  list  ciin  be  designated  as  the  detatdt  when  yu«i 
cieate  the  alert's  item  list,  lliese  liuttuns  arc  usually  marked  as  tlie  "OK"  and 
"Cancel"  buttons. 


Check  Boxes 

A  check  bos  item  (Checkltcm)  is  always  associated  with  a  parameter  that  can  be  in 
une  of  two  stales:  on  and  off.  selected  and  not  elected,  bi^^h  and  low,  and  so  on.  A 
check  bnx  appears  as  a  small  square  in  the  dialog  bos.  When  it  is  nn,  its  value  is  1. 
and  it  has  an  X  drawn  in  it.  When  it  H  off,  its  value  is  0,  and  the  square  in  hollow. 

Tlic  ItemDescr  field  in  a  check  biL^t  template  contains  a  pointer  to  the  ntune  of 
the  eht'L-k  bos.  The  name  is  drawn  to  the  right  of  the  ebeck  hax.  inside  the  item  s 
display  r<iLt3nglc.  IteinValue  contains  the  initial  value  cit  the  check  bo\  and  tan  be 
either  1  (onj  or  0  iotf ). 


Radio  Buttons 

Radio  button  items  (Hadinltem)  usually  appear  in  groups  of  two  or  more,  with  each 
radio  button  repres*-nling  a  diiferent  value  that  may  be  lissocialcd  with  one  particuhr 
parameter  of  interest  to  the  appli nation.  The>  appear  as  small  circles  in  a  dialog 
ho\.  and  the  one  diat  is  on  (value  I)  has  a  smaller  black  tircle  inscribed  in  it.  The 
radio  button's  name,  pointed  to  by  ItemDeser.  appears  to  the  ri^bt  of  the  button. 

A  radio  button  derives  its  name  From  the  fatt  that  when  you  .select  one  by  cliekins 
it.  ail  other  buttuni  in  the  ^roup  are  turned  off.  just  like  when  you  select  a  station 

nn  a  standard  car  radio. 

TE  is  possible  to  assign  associated  radio  biilton.'i  to  the  same  lamily  su  that  when 
one  is  turned  im  iill  the  other-S  will  automatically  turn  off.  To  do  this,  put  the  famdy 
number  (From  0  to  i27j  in  bits  0  through  6  of  IttinFkg. 


Scroll  Bars 

Scroll  bars  have  already  been  di.scussed  in  connection  with  the  Window  Manager. 
You  can  use  them  to  reflect  the  value,  in  pictorial  form,  of  any  measurable  quantity 
that  might  take  on  a  ranee  of  values.  For  example,  the  position  of  the  thumb  in  a 
vertical  scroll  bar  might  represent  the  amount  of  fi  ee  ipacc  on  a  disk. 

The  ItemDeser  field  of  a  ScmllBarltem  is  a  pointer  to  an  action  priK.ediire  Hhat 
is  called  when  any  part  of  the  scroll  bar  is  selected.  For  inforniiition  on  how  to 
design  such  a  coiitn>]-  refer  to  die  A/J/We  Ucs  Toolbox  Reference.  If  the  pointer  is 
0,  the  Dialog  Mana^ier  does  nothing  special. 
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A  scToI]  bar  can  take  on  values  from  0  tn  29(1;  this  nmgf  is  reflet-teJ  by  tlie 
position  of  the  thumb  on  the  bur  idativc  to  the-  (.'nd  p<iints.  ItemValuf  LOTilaiiis  the 
initial  value  of  th*  scroll  bar 

Tbe  appearante  of  the  control  can  be  si't  usin^  bits  U  to  4  uf  Itt^mFLag.  These 
bits  have  ihe  following  mranins-s; 


bit  0  1  =  draw  up  Jnuw  on  scnill  har 

bit  I  1  —  dmw  down  Lirrow  on  kltoII  bar 

bit  2  1  =  draw  lei't  iirrow  on  scroll  bar 

bit  3  1  =  draw  right  nrrow  on  ^crull  bar 

bit  4  1  =  horizontal  scroll  bar.  0  =  vertical 


The  JtemFlag  value  for  a  horizonta]  scroll  b^r  with  arrow?  would  lie  SOOIC.  for 
example 


User  Control  Items 

The  first  type  of  user  control  item  (UscrCtlltem)  is  a  custom  control  designed  in 
accordance  with  the  siM'cificationsinf  ihc  Omtrol  Manager.  For  these  types  of  items, 
ItemDcscr  pointji  to  a  control  dcfiiiitiim  prnct'duii^.  iiiid  ItKmViiliic  contain:i  the 
initial  value  of  the  Lonlrol.  For  iiif.triicti(jn.s  on  buw  to  desijin  custom  controls,  refer 
to  llie  Control  .Vliinajjer  chapter  of  the  Ajiple  lies  Tnufhitx  Reference . 

The  other  Ivpe  of  user  LtHilrol  item  ( tIserCilltemS)  is  uselul  if  vuu  want  to 
implement  any  <:ontrol  defined  hy  the  Control  Mana(;er,  LtemDescr  p<iints  to  a 
parameter  block  tliat  contain^i  the  address  of  the  definition  pnK'cdure  for  the  L'cmtrol, 
eI  puintcr  to  the  title  ol  the  cuntrol.  tbe  vie%v  ^ize,  and  the  data  size. 


Static  Text  anA  Long  Stdtic^  Test 

A  regular  statif]  text  item  (StatText)  is  a  string  of  up  to  255  characters  to  be  drawn 
in  the  dialog  box.  It  is  said  to  be  static  because  you  canno!  edit  it.  A  long  static  tc^ict 
item  (LonsStatText)  is  similar  to  n  StatTcNl  item,  bnl  it  can  hold  up  to  32,767 
eharacteri.  lioth  these  itenihi  iire  used  for  sntb  purposes  as  dispitiymg  commands; 
dis[>laying  expliinatorv'  inessaRes,  or  posing  (pw-stions. 

For  a  StalTexl  item,  the  ItemDescr  field  in  tbe  item  template  ptiints  to  the  string; 
(preceded  by  a  leusth  byte)  that  comtains  the  static  text.  The  ItemValue  field  is 
undefined.  For  a  LnngStatTest  item.  ItetnDrscr  points  to  tbe  start  of  the  text  (no 
preceding  length  bytel.  IteinValue  contains  the  Ictifrth  of  the  strinj;. 

To  define  a  static  text  item  that  is  tn  bg  driiwn  on  more  than  one  line,  you  must 
insert  carrisiRe  return  codes  (,^S('II  $0i;))  inside  the  ti"ct  strint;.  The  Dialog  Manager 
does  not  antomatitally  wrap  text  at  the  item  reetanf;le  boundary'. 

Be  careful  to  make  tbe  item  rcetanslc  deep  enough  to  hijld  tbe  text.  If  it  too 
shallow,  tbe  text  will  he  clipped.  If  you  are  drawini^  u  .siitgle  line  of  text  usin|{  tSie 
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sysCem  font,  the  depth  should  he  at  least  nine  rows  (the  ascent+desceiit+leading 
nf  the  font). 

It  is  often  convenient  to  be  able  to  change  the  precise  wording  of  a  static  text 
item  after  it  is  initiiilly  defined,  by  inserting  filenames  or  jihrases  which  cannot  be 
predictec!  in  advance  Tlie  ei5sief;t  way  tn  dti  this  is  to  nsc  the  '0.  '1.  "2,  and  "3  text 
pbt'c  hnlders  when  Von  first  define  the  static  text  ittm. 

YoQ  can  assif^n  a  text  stritiR  tn  each  of  thE,!ie  place  holders  to  ensure  that  when 
the  dialdK  Ixjx  is  drawn,  the  strinj^s  are  substituted  for  the  place  h^ilder^i.  The 
iiLstrutjtiun  Lu  use  for  this  is  _ParamText: 


PushPtr  StringD 
Pii5hPtr  String! 
Pu^hLong  ifO 
Puat^Ptr  String^ 


jSt  r  Lng  far  "D 

;Strlrg  -for  "1 

ifDoTi't  -chaTige  "2  strirg) 

iSt r I ng  for  "3 


StringO  STR  'placeholder  0' 
String!  STR  'placeholder  1' 
Strings      STR      '-Ith  placeholder' 


If  you  do  not  want  to  change  a  partieular  string,  pii&h  a  lon^  word  U  on  the  stack 
instead  of  a  pointer  to  the  string.  This  was  done  for  the  "2  place  holder  in  the 
example. 

Suppose  you  use  a  dialog  bo.iE  to  ask  for  verification  of  a  disk  Forinatting  operation, 
Instead  of  nsiiip  a  general  static  text  item  like  "Are  you  sure  yon  want  to  erase  the 
diski*".  you  can  define  an  item  such  as  "Arc  you  sure  you  want  to  erase  '0?"  You 
can  then  use  _FarainText  to  suhstitTite  for  "0  the  actnal  name  of  the  disk  selected. 
This  must  be  dflne  before  the  dialog  is  displayed,  of  cours.e. 


Editable  Line 

An  editable  line  item  (EditLine)  is  a  sinj^le  line  of  text  that  may  be  edited  using  the 
standard  editing  techniques  supported  by  the  LineEdit  tool  set.  The  text  can  be  up 
to  25.5  characters  Iohr  and  is  enclosed  by  a  rectangle. 

Yon  must  he  careful  to  ensure  that  the  height  of  the  rectangle  for  an  EditTJnc 
item  is  at  lea-st  two  rnws  greater  dian  the  height  of  ihf  font.  If  you  are  usinp"  the 
system  font,  for  CNaniplc.  the  reclangk'  height  innst  bf  at  least  11  mw.s,  If  the 
rectangle  height  is  lower,  no  characters  will  appear. 

The  standard  LineEdit  editnig  techniques  i\rc  as  follows; 


An  insertion  point  i^an  be  selected  by  clicking  the  mnujie  at  any  position  in  the 
text  strinj^.  The  insertion  point  is  marked  by  a  blinking  vertical  bar;  suhseqiient 
characters  will  be  placed  at  dii:^  locution. 
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A  range  of  text  can  he  selected  by  dragging  ttie  mouse  across  the  text.  (Selected 
text  appears  as  white  tliaratterii  d^ainst  a  black  backfiround.)  A  si'lpttion  range 
is  delftt'd  when  a  subsequent  Lliarai.1er  is  entered. 

A  worti  can  be  selected  by  double-elickin^;  the  mouse  anywhere  in  the  word. 
All  the  text  can  ijo  selected  by  triple-t'l it-kin 

A  selection  mnge  can  be  extended  by  eUcking  while  holding  down  the  Shift 
key. 

Pressing  Contral-\  will  erase  the  entire  line. 

Pressing  ContruUY  will  cra.>ic  cvcrytliing  from  th<"  (.'urrent  insertion  point  to  the 
end  of  the  line.  11  a  sdeetiun  range  is  active,  it  in  deleted. 

The  left-  and  right-arrow  keys  ean  be  used  to  move  the  inseitimi  point  back  and 
forth  in  the  text  line. 

Pressing  Control-F  will  delete  the  character  at  the  insertion  point  or  will  delete 
the  selection  range. 

Pressing  Dcfctp  will  delete  tlit-  tliaractcr  (o  the  left  of  the  insertion  pcjiut  and 
move  all  the  characCcrj^  to  llie  rii^lit  of  the  insertion  point  one  pii.sitinn  to  the 
left,  or  will  delete  the  selection  range. 

Pressing  any  other  ke>'  will  insert  that  key  character  at  the  Insertion  pointi  if  a 
ran^e  is  selected,  the  characters  in  the  raoge  will  be  deleted  and  replaced  by 
the  key  character. 

Open-Apple-X,  Open-Apple-C.  and  Open-Apple-V  can  be  nsed  to  perform  cut. 
copy,  and  paste  operations,  all  of  which  involve  a  data  area  called  the  clipboard. 
Cutting  transfers  the  selection  ramgc  to  ihe  clipboard  and  removes  it  from  the 
line.  Copying  does  the  s;iine  thing,  hut  without  reniuviiifi  il  from  (he  line. 
Pasting  involves  transferring  text  from  the  clipboard  to  the  line  at  the  insertioji 
point  (if  a  setection  rajige  ii  active,  the  .^election  is  deleted  first). 

U,sing  an  editable  text  item  for  user  input  makes  il  unnec-essarv-  for  you  to  write 
your  ovvTi,  line  editcir. 

For  an  EditLiJie  item,  IteniDescr  is  a  pointer  to  the  string  (preceded  bv  a  Eength 
byte)  that  will  be  shown  when  the  dialog  box  first  appears,  The  ItemValue  field 
contains  the  maximum  length  of  the  siring;  the  possible  choices  are  0  to  255. 

When  a  dialofi  bux  i.*,  drawn,  the  first  EditLine  item  is  totidlv  selected  so  that 
you  can  delete  it  quickly  by  pressing  a  key  to  enter  a  new  string.  If  there  iii  more 
than  one  editable  text  Ihjx  item,  you  can  use  tht-  Tab  key  to  move  from  one  lt>  the 
next.  If  you  arc  in  the  last  text  bo.t  when  you  press  Tab,  ynii  will  go  to  the  first  box. 

As  will  bp  discussed  later,  the  Dialog  Maiiager  contain.^  (unctions  you  can  use  to 
change  the  EditLine  te\l,  to  determine  its  contents,  and  to  select  any  portion  of  it. 
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[cons 

An  iwjn  (konl(*fin)  is  A  Static  item  that  defines  a  small  rf  L'tan^ular  image  on  the 
strtrmi.  Thi'  IteniDescr  fifM  in  a,  template  toiilaiiis  a  handk  (not  a  pointer)  to  the 
icon  definitittn.  IteinValue  is  licit  used. 

An  iujn  definition  begins  with  the  pixL-l  dimensions  of  the  ieon.  in  rectimgle 
form,  (The  width  of  the  tttm  must  lie  ;l  multiple  of  H.)  FnWownn^  the  reitansle  arc 
the  bylea  defining  the  bit  jmase  of  llie  itvu.  When  dLsiyninK  an  icon,  keep  in  mind 
that  there  are  two  bits  per  pixel  in  64l)-by-2.fK)  mnde  and  four  bits  per  pixel  in  320- 
by-20O  mode, 

Here  is  the  definition  for  an  iwin  in  640-by-20G  mode  that  looks  like  an  asterisk; 
nylcon  flMOP 


DC 

1 '  0 ,  a ,9, IS' 

OC 

H'FFfOFFFF' 

;Bit    image  defining  each 

DC 

H'QFFOFFOF' 

1(2  pixels/nibble  in  6^0 

DC 

H'f OFOFOFF ' 

DC 

H  'FFOOCFFF • 

DC 

H  '  OOOODOQF ' 

DC 

H'FFOOOFFF' 

DC 

H'FOFDFaFF' 

DC 

H'OFFOFFOF' 

DC 

H'FFFOFFFF' 

Remember  that  two  U  liit»  refer  to  a  lilatk  pixel  on  llie  fi4lf-by-200  screen,  and  two 
1  bits  refer  to  a  white  pkel. 

Pictures 

A  picture  item  ^ficlleml  contains  a  handle  t<j  i\  QiiickDraw  II  picture  in  its 
ItemUener  field.  The  ItMnV'abie  field  a  iu?t  defined- 

ITser  Item 

A  user  item  (Useritem)  i-*  one  wIiosl-  ap]iearance  and  behavior  is  defined  by  the 
applied  liuii.  For  'iuch  iiri  item.  ItemDescr  pttlnts  to  an  item -definition  procedure 
and  IlemViilue  is  nnt  used. 

The  Dialog  Manager  ealh  an  ileni-deflriition  ]jrncedore  with  a  JSL  instruction 
after  first  pushing  two  parameters  on  the  stack:  a  pointer  to  the  dialog  [long!  and 
the  ID  [Uiinber  ol'  the  itfut  to  draw  (word).  Thi^;  information  is  provided  so  that  you 
cHu  ase  the  same  itcni-dcfinitinn  procedure  to  handle  many  user  items  and  dialog 
windows. 

After  the  procedure  docs  what  it  is  designed  to  do.  perhap^i  drawing  a  fancy 
holder  or  playing  a.  tune,  it  mast  remove  the  inpot  parameters  from  the  stack  and 
return.  Here  is  the  code  fragment  you  will  need      do  this: 
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LDfi 

LDfl 
STft 


2  ,S 

e,s 
1  ,s 

7,S 


RemD\iP    parameters    t>y  movmg 
the  retucfi  addres?  up 
by  6  bytes 


TSC 
CLC 
ADC 
ICS 
RTL 


i^dd  E  to  the  ^tack  pointar 


The  procedure  ends  with  RTL  because  it  is  called  with  a  JSL  imtruetcon. 


DISABUNC  ITEMS 

Any  item  in  a  dialog  can  be  marked  as  dii^abled  by  adding  the  llffinDii^ahlL'  L-Liinst;int 
($8000)  to  its  item  type  ecide.  Disabled  items  slill  ItJtjk  the  same,  hut  user  aLtivity 
Ltl  them  is  nut  repurted  tu  the  appliLation.  It  is  a  i^ixid  idea  ia  disable  static  items 
like  icons,  pictures,  and  text  su  that  (lie  applici^tion  dues  not  have  to  hother  deaJinji; 
with  mouse  activity  in  them. 


ADDING  ITEMS  TO  DIALOG  BOXES 

If  you  have  created  a  dialog  hox  with  NewModalDialoR,  yuu  need  tu  add  itemi  ta 
it  before  ai:ythiilg  ysel'lll  will  appear  Ou  the  screen.  Even  il"  you  have  used  Cet- 
NewMfidalDialos  with  predefined  items,  you  may  want  to  add  new  items  to  reat't 
ti>  changes  in  standard  operating  tonditions. 

To  add  an  item,  nse  cither  GclNcvvDltem  or  NewDltem.  U^ing  GetNewDlteni 
is  the  easies!: 


PuahLong  tbeDielag  ;Pu5h  dialog  poiTiter 

PushPtr  lltffnTetnpJale  ;Pu5h  poinlpr  to  It  em  1  empla  t  e 
_CetNewDI tern 


As  yoii  can  see,  GetNewDItem  exiJetts  tu  find  the  item  parameters  in  a  template. 
The  forn]  of  this  template  is  the  iame  as  described  in  the  previuus  seetiun. 
NewDltem  expects  you  to  push  the  ilejn  parameters  iin  the  stack  instead; 


PuihLong  thtDialog 

PgshWord  llemlD 

PuShPtr  I temRect 

PushWord  ItemType 

PushLong  ItefTiDescr 

PushHord  llemVaiue 


;  D I  a  1 og  pointer 

!  I  t  em   ID  number 

jPoititer   to   item  rectangle 

; [ lem  type  code 

;  M em  desc r i p t or 

;  I  tern  value 
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PushWord   Itemriag  ;itein  flag 

PuahLong   ItemCiOlflr  iPtr    to   item  color    table  (O-default) 

_Neu'Ill  tercb 

CHANCING  ITEM  ATTRIBUTES 

Matiy  Dialog  Manaiser  fiinctkiiis  can  be  used  to  read  and  change  iittritjutes  of  tlie 
items  ill  a  dialog  box  ittiii  list. 

Get  IText  Rrli.irii  text  i>i  A  ytalTt'M  or  EcljtLine  item 

Set  I  Tex  t  Hvl  the  tf\t  nl  ;t  litbitTt-^it  or  KclitLine  item 

Sel  IText  Set  thi*  sflectiun  range  al'an  Edit  Lint  iteui 

GetDItemType  Get  the  itt-m  type  code  fnr  an  item 

SetDl  tefTiType  Set  the  ik'in  typf  code  for  an  iU'm 

Get  D  I  t  emBox  Brlnrn  tlit=  di.s]jliiy  reLlan^lr  fnr  an  item 

SetDI  temBox  Set  tin-  display  rc-ctanuli^  for  an  item 

GetDef  Button  Rt-him  the  lUof  liic  default  ittm 

Se  tDef  Bu  1 1  on  St't  the  ID  [>f  the  defuul!  item 

Ge  t  D  I  t  emVa  1  ue         Return  the  itemV'alue  fnr  an  item 
5etD  I  temValue         Spt  tli*-  ittmSaluf  \hr  an  itt-m 
H  i  deD  I  t  em  Eraav  ttn  (tern 

BhoiwDI  tem  Display  a  hidden  item 

F  1  ndD  I  t  em  Rptum  the  ID  of  rhi'  item  at  a  Riven  point 

Di  aab  leOI  tem  Ui^rablf  an  ilcin 

Enab  leDl  tem  Enable  an  item 

Of  these  funL'tiojis,  only  GetlText,  SetlText,  SellTi,-Nt,  Get  D  Item  Value,  and  Set- 
DltemViihie  are  LOinmnnly  used  hy  ;ippIita!ioiis.  Vnu  may  find  a  need  for  the  others 
if  vciu  need  to  write  a  complex  filter  prueedure  (see  the  discussion  of  filter  pRict-dures 
litlnwJ. 

"I'his  SfL'tion  disenssrs  ways  of  using  this  grniip  af  five  major  attribute  TOmmaiids. 
For  ii](orinati,on  on  the  others,  refer  to  the  Apt'^e  llCa  Toolbox  Reference- 

Dealing  with  Text  Items 

It  is  often  neeessary  to  detrmfiine  l!ie  tfst  assDC-iatcd  with  n  particidar  EditLine 
item  no  dial  the  applit^atinn  can  take  die  user's  nipiil  and  deal  with  it.  F((r  this,  use 
Gciriext: 

PuahLorg   theDtalog  ;Dialog  pointer 

PushHord    llerrlD  ilD  number  of  item 

PuatiPtr     thcText  ;Pointer   to  string  area 
_Get JTpxt 
RTS 

theTeat  D5             25S  ^Space  for  returned  string 
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lilt-  space  you  rcscne  for  iheText  mu^t  hr  nnc  hyte  greater  than  the  maximurn 
len^lli  of  thtf  text  itfm  ptTiiiiltecl,  Tlit-  t-xtra  hytc  is  fnr  the  leadinj;  length  bytt-  You 
can  also  use  GellTtNt  with  a  SlalTfSt  ittm  if  ynu  wish. 

To  t'han^f  the  texl  of  a  StatText  iir  EditLine  item,  vise  SttlText: 

PushLong  theDialog  ^Ojai&g  pointer 

PuahUord   itpmlD  ; Item   ID  number 

PushPtr     My  Text  ;The  new   leit  ^ti-ang 
Set  I  Ten  I 


MyTexl      STR  'This    la  d   new  string' 

The  string  at  MyText  must  bp  pret-edetl  by  a  len^h  byte.  You  can  also  change  the 
text  of  an  ilein  iisinn  ihf  PsiramTcsl  coiilinaiul  deitTiht-d  rarher  in  this  chaptL-r.  For 
this  to  work,  the  item  text  iTiiist  crHiti^in  place  huld(?r  eharactcrs  ol  the  fonn  *[>,  '1, 
■2.  anil  "3. 

Annlher  thinji  you  ljh  do  is  preselect  all  or  a  portion  of  nn  EditLlne  itfiii. 
^ieU'ctcd  text  is  hifihli>;hted  m  while  letters  on  a  black  liackyround  and  is  deleted 
iind  replaced  when  you  type  a  character  from  the  keyboard.  If  ihe  item  contains  a 
default  >itrins.  you  will  probably  want  tci  Select  the  entire  string,  so  llie  Dialog 
Mujia^cr  iloes  tliis  iur  yuu.  Tbut  way,  the  default  will  disappear  when  the  user  types 
A  eharaeter  to  chanRe  the  entry. 

Stipptisc  the  iLser  is  to  enter  an  EdilLine  item  that  ends  v^ith  a  fllcname  suffix  of 
■'  ASM'  .  If  you  display  a  default,  you  ina>  wish  tu  hishbiiht  everything  hut  the  suffix 
so  that  the  usor  does  nol  have  to  ri? t>'pe  the  suffix  if  he  enters  a  new  narae.  Here 
is  how  ynu  arrange  for  the  jiroper  highlighting  using  SelJTexti 

PushLong   tt^eDialag  ;Didtcg  pointer 

PuatiWord    itemlD  ;]tein   ID  Tiumber 

PushWord  #0  ;Starling  char,  position 

SEC 

LD'^  NameLen  ;Get   icTigth  namft 

SBC  ;Subtract  5uffix  5iic 

PHfl  lEtiding  chiafac  let'  poaitio-n 

.SellText 

The  startijlR  and  ending  pQ5.ititin  parartieters  pas'it'd  tn  .SellTe\t  run  from  0  up  to 
the  niaxiiriLiiii  size  i>f  the  text  siring.  A  0  value  rcfer,«i  to  a  position  to  the  left  nf  the 
first  character,  1  refers  t«  a  position  to  the  left  of  the  spcond  character^  and  so  on. 
If  Che  .startiJig  and  ending  positions  are  equal,  a  blinking  vertical  bar  appears  at  that 
position.  Typed  charaeterh  arc  inserted  at  this  poinl. 
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Keading  and  dianging  ihe  Ilem  Value 

To  read  the  current  numeric  vulue  of  an  item,  use  CetDItemValue  as  follows: 


PHA 

PushLcng  theDiatog 
PuahWord   1 1  em  IS 
_GetDItemUalue 
PLA 


;  Space   "for  result 
;  The  d  La  I  99       I  fi  tei^ 
;The    ID  of   the  item 

iGel  the  rESul t 


Of  iL>ourse,  this  functitm  is  useful  nnly  for  those  items  that  use  llie  ItemValue  field 
in  the  item  templatt;.  For  check  Imxt-s  and  radio  buttons,  llie  value  am  be  0  [off) 
ar  1  (on).  Other  values  are  possible  for  scroll  bar  and  user  control  items.  For  a 
LonsStiitTest  item,  the  value  is  the  lensth  of  the  text. 

Use  SetDltf-'mValue  to  assign  a  particular  vjlue  to  an  item.  You  will  use  it  moat 
often  to  select  and  deselect  check  boxes  and  radio  buttons.  For  example,  if  you 
detect  a  mrnise  ditk  iii  a  cheek  box  that  is  off,  you  would  turn  it  on  (put  m  X  in  itj 
using  the  folluwing  itis  I  ructions : 


PuahUlord  #t 
PuahLorig  IheDlalog 
Pu  ahUord   1 1  em  1 D 
SetDltemValue 


Hew  va 1 uc   { 1 =Bn ) 
Dial Dg  pointer 
ID  of   di^laC|  Item 


When  yon  turn  011  a  radio  huttt>n  iteoi  like  this,  the  Dialog  Manager  automatioidly 
turns  off  all  radio  buttou  items  with  the  same  family  number.  This  is  in  keeping 
with  the  user-interface  guidelines,  which  insist  that  only  one  radio  buCton  in  a  sroup 
may  be  on. 


USING  DIALOG  BOXES 

The  proper  way  to  handle  a  dialoR  box  once  it  is  on  the  screen  depends  on  whether 
it  in  a  modal  or  moddess  dialog  bos- 


Modal  Dialog  Buxes 

As  snon  as  you  define  a  modal  dialog  box  im  the  screen  w-ith  NewModalDialog  or 
CetNewModalDialog  you  must  call  ModalDiiduR  to  monitor  events  withni  the  bos 
and  get  a  result  indicating  what  item  was  selet-ted.  Yon  can  then  deal  with  the  result 
a.s  you  set  fit  before  calUng  ModalDinlog  once  again  to  get  more  input  or  disuiissing 
the  diialog  box  if  a  button  was  selected. 

To  dismiss  a  box,  call  CloseDialug  to  erase  it  from  the  screen.  Tliis  function 
requires  only  one  parameter,  a  dialog  pointer. 
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Td  use  ModalDiidofi,  push  space  for  a  word  result  and  ihen  push  the  address  of 
a  filter  procedure: 

PHA  ;Spflce    for  result 

PuahPtr  FilterProc  ;Poirter   to   filter  pracedLire 

PLfl  of   item  selected 

A  filter  procedure  is  a  subrmitme  ModalDialop  calls  aftiT  it  detects  an  event  Wt 
before  it  r<?spnndji  lo  il,  Ry  usinR  auch  »  pruLt-diiri?,  you  am  niodify  the  efleet  oi  an 
event  any  way  you  like.  If  ynu  are  not  using  a  tustom  Rlti-r  procedure  {the  usual 
case),  jest  push  &  Inn^  wtird  zero  on  the  stack.  This  invukes  the  ^tandll^d  filter 
procedure  wliieh  cnnvcrts  a  press  of  the  Return  key  to  a  mouse  clitk  in  the  box's 
default  button;  !t  siso  handles  the  keyboard  commands  for  cut  (OpenApple-X),  copy 
(OpBiiApple-C),  and  [>aste  (OpeuApple-V)  operations  properly. 

A  sample  filter  prwedure  is  shown  in  listinH  a^2.  When  ModaLDialog  calls  it, 
there  is  a  result  airdce,  three  long  values,  and  a  three-hytc  return  address  on  the 
staek; 


result  (uiOrTl] 

dialog  pointer  (long] 

pointer   to  event   record  fioTig) 

pointer  lo  llemHit  wariable  (long] 

returr  addre^^    (3  bytes} 


When  the  filter  procedure  ends,  it  must  remove  the  three  long  input  parameters 
from  the  stack  hy  raoving  the  return  address  up  by  12  bytes  and  adjustinp;  the  staek 
pointer  accordingly. 

The  resvdt  of  a  filter  procedure  is  a  Boolean  value.  If  it  is  true,  ModtdDialog  ends 
and  returns  the  ID  number  which  the  filter  prcxedure  returns  in  ilemHit.  If  it  is 
false,  ModalDialug  handles  the  event  in  its  usual  way. 

The  fiber  procedure  can  tell  what  lypc  of  event  it  js  dealing  with  by  checking 
the  "what"  field  of  the  event  reLord.  To  force  the  event  to  be  ignored,  it  can  put  a 
0  in  the  What-  field  to  convert  the  event  lo  a  null  event. 

The  procedure  in  listing  filters  yut  keytxiard  control  characters  (other  than 
those  needed  for  editing)  in  tliis  way  Without  thi.s  filter,  L-ontrol  characters  appear 
as  inverse  question  marks  in  an  EditLine  item. 

When  designing  a  custom  filter  procedure,  ynu  should  strive  to  retain  the  be- 
havior uf  the  default  filter  procedure.  To  do  this,  set  the  hij^i-order  hitof  FilterProc  s 
address  when  yon  pu.sh  it  on  the  stack  lur  ModalDialoR.  This  tells  MudalDialog  to 
pais  events  to  the  standard  filter  after  the  custom  filter  procedure  deals  with  them. 

When  ModalDialog  takes  over,  it  handle.'!  any  update  events  related  to  the  dialog 
{caused  when  a  control  item  like  a  button  or  a  check  bos  chanjijes  value)  and  monitors 
all  events  until  an  active  item  is  selected,  It  beeps  if  the  mouse  is  clicked  outside 
the  dialog  window  and  ignores  all  clicks  inside  the  window  if  they  are  not  alsu  inside 
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the  display  rectangle  of  an  Fnaliled  item.  Moiise-dowTi  events  in  trtntrcil  iUms,  such 
as  buttons,  radio  buttons,  and  check  boxes,  arc  niOiiitorc>d  until  thr  mouse  is 
released;  il'  thr  mouse  is  not  still  in  the  item  upmi  rL-lease,  tbe  diek  is  ignored. 

When  ModalDialuf^  finishes  il  returns  the  number  of  the  item  selected.  The 
Lipplk-^iLioL  can  then  deal  with  this  rnsult  as  it  wishes;  it  ciiu  then  either  remove  the 
diidop  has  from  the  streen  ur  ctlll  MndalUialos  unee  a^jain. 

The  acfUiti  a  program  take^  when  MoiliilDialoj;  returns  a  result  depends  on  the 
type  of  item  seletled.  If  it  wii  a  cheek  box,  the  bos  ';hould  be  rhfeked  if  it  was 
previou^ily  unL-Wecked  or  vie*  ver!.a.  11  il  was  a  radio  button,  ihe  radio  button  shuuld 
be  seleeted  and  all  i.ther  nidio  buttons  in  the  group  should  be  deselected-  Standard 
subroutines  for  doing  this  are  shown  in  listings       and  8-4. 

When  a  button  is  selcLted.  ynii  should  read  and  sa^-  e  the  settings  of  the  variable 
ittims  in  the  diwlos  di^imiss  the  dialng  by  reiiiovinft  its  vtnndow  from  the 

screen  with  Closer>ialc)j^. 

Key-down  t'vetits  are  processed  by  MndalDialog  only  ]f  there  isim  EditLine  item 
in  tiie  dialog,  Tf  the  EditLine  item  is  enabled,  its  item  number  is  returned  after 
even,-  key  press,  If  it  is  not,  n«  item  number  is  returned,  but  MndalDialog  still  lets 
yoii  edit  the  string  in  the  test  hos,  Il  is  probably  best  to  disable  EditLine  items  (by 
adding  S80(J0  to  tht  item  rode  in  the  item  template}  so  that  you  do  not  have  to 
ki-ep  looping  back  to  ModalDialop  lifte  r  every  key  press.  Instead,  after  a  button  is 
pressed  to  dismiss  the  dialog,  vuu  can  use  G<?tITcxt  to  determine  the  final  valut  of 
the  text  string. 

Tlie  Tab  key  is  used  tn  move  thf-  text  insertion  cursor  from  one  EditLine  item 
to  the  next.  If  yau  are  in  the  ktst  EiUtLine  item  when  you  press  Tab,  you  will 
ptoeeed  to  the  first  such  item. 

Mouse-down  aetiv  ity  in  EditLine  items  is  automatically  handled  by  ModalDialog 
io  accordance  with  the  LineEdit  spec iheations  deseribed  earlier.  In  fact,  Modal- 
Dialog  ealls  LicieEdit  to  handle  thc&e  events. 

Modeless  Dialog  Boxes 

A  modeless  dialog  box  is  a  bit  more  difficult  to  handle  than  a  modal  dialog  box. 
When  a  modeless  dialoj;  l>ox  is  on  the  screen,  the  user  is  not  re-stritted  from 
performiui;  other  operations  (such  as  aotivatin)j;  another  winditw  or  seleetiuR  a  desk 
iKcx's.'ior\'»  before  dismissing  it  to  remove  it  from  the  sereen.  In  this  respect,  a 
mo<leless  dialos  box  like  any  other  standard  window,  although  it  ointanis  various 
controls.  Unlike  ,\  modal  dialog  box  or  an  akrt  hos.  it  does  not  retain  Lflntrol  until 
you  seieet  an  active  item,  Vtiu  simply  feed  it  eveuts  oiw  at  a  lime  and  it  returns  a 
Boolean  result  that  tcUs  you  whether  the  event  related  to  the  dialog  box  or  not. 
To  create  a  modeless  dialog  window,  you  most  use  NewModeless Dialog  as  follmvs: 

P(_fi  ;apacetarreault(lorig) 
PLA 

PushPtr   dBouTid^Rect  ;Poi.rter   Id  window  reclangle 
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Figure  S— t.     A  Muck'less  Dialug  Box 


Search  for  Text 


Begin  Search 


PushPlr  dTille 
PdshLorg  dBehincf 

PushWord  dFlag 
PuahLcng  d&efCon 
PushPt  r     dFul ISize 
_NewnoiJe  J  essDialog 
PapLofig  DtalcgPtr 


■.Pointer   to  dialog  tjtle 
iPointer    tc  windQw   tn  front 
;    of  dialog  w-i  ti dow 
jLJindow  frame    hit  veetoi" 
;  reference  conatarvt 
jPomtsr    ti>  zoom  rectangle 

ipap  p{)  inter    to  dialog 


[if  these  paraniftt-rs  arc  srir-explamtonv  N()rm;illy,  you  set  dBeliind  to  -1  ia 
brinf;  the  modeless  dialii^  hux  up  in  froiil  ui  iilJ  uther  windows.  The  dFliip  v*?thir 
lias  the  .same  ineaninR  as  the  window  frame  vector  in  a  Nc^^  Window  caih  most 
dialtic  windows  have  only  a  close  Ixix  and  a  title  art-a 

'file  paraincter-s  passed  t{}  NcwModi^lessDialoR  do  nut  inciiidi-  the  items  to  be 
drawn  in  the  dialoR  window.  Ytiu  must  :«ld  these  liy  making  calls  to  GetNewDltem 
or  NewDltem. 

The  program  In  listing  S-5  shows  hnw  lo  define  a  iiioddc.'is  dialog  hn\.  The  box 
i(  defines  is  shown  in  figure  8— i. 

The  DialoK  Manager  iiiiikfs  it  siimcwhat  easier  to  deal  wdh  a  modeless  dialog 
box  than  a  standard  wiiidtnv,  Wheiu-M-r  ynur  progrant  talis  Tai-kMaster  or  Cet- 
NextEvent,  if  should  €"a!l  IsDiaionEvent  to  dptcnniiie  whtflhtr  the  current  event 
relates  to  the  modeless  dialog  Ikjs.  (se*?  the  program  in  li-stinc  8-6): 


PHfl  ^Space  for   Bcolefln  I'esulE 

PiiahPtr   EuenlRecord       iTastMaater/GelNeilEuent  record 

PLA  iPop    IruE/false  result 
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The  EventRfcord  i&  the  one  used  with  TaskMiister  nr  CetNcstEvenl.  LisHnjj  S-6 
shcnvs  Kow  to  Imndk-  events  in  inodrlesi  dialog  bfjxL-s, 

If  the  result  false,  the  event  was  nut  dialng-ii'liiled  and  tan  lie  processed  as 
usual.  Thi-^  includes  events  tor  which  TaskMiister  reiiirns  wIiiMenitBar  or  win- 
Special,  unlc-ss  it  was  caii«:d  by  a  kcy-dau'ii  event  (thiit  is,  unless  tlje  user  entered 
a  keyhoard  ('i|uivalent). 

Special  etlit  items  itivulviiig  niodeles)^  dialog  windows  can  he  handled  by  tailing 
a  snhrnutine  like  the  nni-  in  listiiif;  8-7.  In  brief,  it  checks  to  see  if  thv  active  window 
is  the  mudeless  dialog  windnw;  jf  it  is,  it  handles  the  special  edit  item  by  cjillinf^ 
one  of  the  following  functions; 

DlgCut  CliI   the  selected  text  and  put   it  on  clipboard 

DlgCcpy  Copy    the   selected   lext    to  the  clipboard 

DlgPaate  Transfer   the   text   on  clipboard   ta   the  document 

DlgDelete  Erase  the  aeleeted  leict  ;   clipboai-d  not  affecteij 

[There  U  no  slmilaj  hiiiction  for  handling  the  special  Undo  item,  An  application 
should  handle  Utido  by  canceling  the  previous  edit  npcration.)  All  tht-se  dialog 
editing  functions  require  only  ime  [jarmncter.  the  handle  to  the  diido;^  record, 
IsDialopHvent  returns  true  for  the  following  events; 

•  Aciivate  or  update  events  for  a  dialog  window 

■  Mouse-down  events  in  the  content  region  of  an  iurtive  dialog  window 

■  Any  other  event  when  a  dialog  window  is  active 

When  Is Diah)g Invent  returns  a  tme  result,  you  norrnally  call  DiidogSelect  tn  process 
it.  If  you  are  using  TaskMastor.  however,  you  du>uld  theuk  first  to  see  if  the 
TaskMaster  result  was  whiMenuBar  or  wlnSpecial.  For  either  result.  TaakMaster 
will  have  highlighted  the  menu  title,  so  turn  off  hlghlightinp  with  HiliteMenu  (see 
chapter  7).  DialogSclt^et  does  not  do  this  for  ynu. 

The  wlnSpecial  results  shuuld  then  be  passed  directly  to  UialogSi-lect  for  pro- 
cessing. If  tlie  modeless  dialog  bo\  has  an  EditLiiic  item,  tlie  item  will  he  edited 
accordingly.  The  wIuMciinRar  results  should  be  dealt  with  separately  because 
DialogSeleet  will  jiot  know  what  to  do  with  thern. 

Here  is  how  to  call  Dialog  Select; 

pj^fl  ;GpflceforBooleanre5Lilt 

PushPtr  EwentPscord  -.  Tastmaster/GetNextEvert  recor 

PuBhPtr  IheDieiog  iDialog  pointer   returned  here 

PushPtr  itemHlt  ;  I  t  eir  number   returned  here 

_Dia 1 ogSe lec  t 

Pl_f^  ;Gettrue/fal5ere5Ljlt 
RTS 
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itsmHit  DS  2 
theDialog  DS  A 


lltcFn  riLiiiiber  returned 
;PoiTilEr   to  dialog  record 


DialggSelect  lakes  tfie  cvpnt,  processeji  it.  and  returns  a  Boolean  rt-siik  indicating 
wlwfthcr  il  related  ti>  an  enabled  tlialufi  item.  If  the  rcstdt  is  False,  it  did  ncit  rcJate 
tu  an  enabled  item.  lUid  ytm  du  not  have  lo  du  anytbing  further.  DialcigSeleqt  always 
returns  a  false  value  if  you  pass  it  ii  window  update  or  aeti\'ate  event;  these  events 
are  p^oee!i^ed  internally. 

If  die  result  is  true,  the  ilemflit  and  theDialog  variables  will  TOtitai]i  the  number 
of  the  item  .selected  and  a  pointer  to  the  active  dialog  recnrd.  You  can  then  dea] 
with  the  result  in  the  same  way  you  dfal  with  :i  re.'iult  returned  b\'  a  eali  to 
ModidDialoj;  fur  a  modal  dialog  Ikjx.  DjalnsSelect  always  returns  a  true  result  in 
situations  in  which  ModalDiaJog  would  have  reported  an  iteni-rekted  event  to  you. 

USING  ALERT  BOXES 

There  are  four  Dialog  Manager  fiinctions  for  displaying  alert  Iwxes  on  l:hc  screen; 

•  Alert 

•  Stop  Alert 
■  NoteAlert 

•  CautioriAlert 

You  call  each  of  these  fimctions  in  exactly  the  same  way.  The  only  differeuces  amonR 
them  are  the  icons  they  di-^pluy  in  the  ft>p  left  corner  of  the  hiK.  Alert  displays  no 
icon  at  all;  StopAlert  displays  an  uctayonal  slop  sign  with  a  hand  in  it;  NuteAlert 
displays  a  talking  person;  CautionAlert  displays  a  yield  .4ign  ^ith  an  exclamation 
mark  in  it. 

The  program  in  hsting  S-S  shows  how  to  create  and  deal  with  an  alert  box. 

Aler!  hf«cs  are  easy  (o  use,  because  all  screen  and  event  activities  are  handled 
by  a  single  function.  This  function  creates  the  alert  record,  draws  the  alert  box  and 
its  items,  interprets  events  until  lui  active  item  ii  selected,  erases  the  alert  from  the 
screen,  antl  disposes  of  any  memory  used  by  the  alcrl  record.  The  function  returns 
the  item  number  selected.  All  ytm  have  to  do  is  monitor  this  result  and  tiike  whatever 
sctioil  appropriate.  Compare  this  with  dialuf;  boxes,  which  require  you  to  use 
different  tunctions  to  create  and  disijose  ofthe  dialoK' 

To  display  an  alert  box.  pass  pointcr-s  to  an  alert  template  and  a  filter  procedure 
to  the  lunction; 
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PHfl  ;!pace  for  result 

PushPtr  fl  l«r  t  Temp]  Sit  e        iPoifiler    t^J  slGrl  tempidte 

PuBhPtr  FilterProc  ;Pointer   to  filter  procedure 

_ftlerl 

PLA  -,  ID  of  item  selected 


Alert  handlt.'^  muurit.-  dicks  much  as  MtKlaLDiulo}'  handler  them.  Thdt  is.  muu&e 
dicks  outside  the  alerl  bos  produL-e  errur  beeps,  and  chcks  in  disiibled  items  are 
iginored,  Alerl  reliinis  ihe  value  of  any  enabled  item  that  is  selected.  For  an  alert 
boK,  oidy  button  ileins  sHoidd  ht'  tiiabled. 

An  alert  template,  like  a  dialog  template,  includes  a  list  of  items  that  are  to 
appear  in  the  alerl  ba\.  Its  exaet  b.lru<.-ture  is  as  follows: 


QG  I't,l,b,ri  ifllert    hoK  rectangle 

DG  I'ftlertlD'  ;ID  number  for  alert  boic 

DC  Il'Stagel'  iFjrst  stage  alerl 

DC  II 'Staged'  ;5econd  stage  alert 

DC  II 'Stages'  ;Third  stage  alert 

DC  n'5tage4'  ^Pcurth  stage  alert 

DC  M'lteml'  ;PDir>terto1stltem  template 

DC  I4'[tem.2'  ^Pointer  to  2nd   Ltem  template 

DC  I4'lte^^lt^'  ;Po:rter   to  Nth   Uem  template 

DC  |4'0'  1  ierc  termiTiator 


The  item  tcmphtc'^  rcfcrrt'd  to  in  alert  template  arc  identical  to  the  ones  discussed 
earlier  in  coniiiec  tioii  with  modal  dialog  boxes. 

Stii%v  byte.s  iiijke  np  an  important  parameter  iti  an  alert  template.  Thfv  define 
the  behavior  of  the  alert  in  each  of  fmir  difl'creiit  stages.  When  yon  use  the  alert 
box  (br  the  first  time,  it  enters  the  first  stage.  As  yon  keep  (.'ullinS  it.  it  progresses 
thniLijtb  the  seeoiid,  third,  and  fnurth  slajjes,  in  that  (ird<?r-  Tlier-eafter,  the  alert  hnx 
always:  bfhaves  as  if  it  was  in  thf  fourth  sta|;e.  ¥oii  tan  reset  the  alert  stage  to  0 
with  HesetAlertSta^e  {310  pararaetersj. 

An  .^lujwn  in  fijjure  S— 5,  the  eh araeteri sties  Li.'jsouiated  with  ^^^ic■h  sta^e  are  what 
the  default  button  is  to  be,  what  .snnnd  is  tn  be  eiiiittrd,  and  whether  the  alert  box 
IS  to  be  drawn. 

For  a  ^iven  stajije,  the  First  twn  bit.s  (0  and  11  eiiiit;un  a  .snund  iiumher  from  0  to 
3.  Ill  most  cases,  this  number  represents  the  number  uf  times  the  speaker  is  to 
beep  when  an  alert  is  called  up  at  tiiat  slaf^e  le\el.  It  is  possible,  however,  to  inv<ike 
a  custuni  sound  proeedure  diat  iiitcrjirets  lhe.se  niLinl>ers  diflerently.  Refer  to  the 
Apijltr  Has  Tuolhiti  Heftrvncf  fur  LiLslruc'tions  on  how  tu  do  this. 

Bit  7  indieates  whether  the  alerl  box  is  lo  be  drawn  on  the  screen.  You  will 
usually  S-el  this  bit  In  1  {display  the  bnxK  but  von  can  iet  it  to  0  if  vuu  dn  niit  want 
the  alert  tu  lit*  displayed  at  lhat  statse  levt^I. 

Bit  6  eoiitruls  whieb  uf  two  buttons  is  to  be  the  default  button.  The  default  button 
is  the  one  selected  when  KeUini  is  pressed  fruui  the  keyboard.  Lf  the  bit  is  set  to 
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Figure  8—5.    The  Fomiiit  of  a  Stage  Bvtr  in  an  Alert  Template 


7 

6 

5 

— 

4 

3 

2 

1 

0 

sound  nunnber  (0  to  3) 

ID  of  defeuU  button 
minus  \ 

1  =  draw  alert  box 
0  =  don't  draw  box 


0,  the  first  button  (usTially  an  OK  button)  is  the  default;  if  it  is  1,  the  second  button 
[usually  a  Cancel  button)  is  the  clelBuIl. 

In  inosl  app] it-Li tions  ytnj  will  probably  want  itafjt  s  to  be  cqiiivdent,  so  nil  four 
byttfs  will  be  thr  ^anic.  For  e.tainpk*,  if  ynii  want  to  beep  the  speaker  oiit-t,  display 
thi-  alert  box,  hikI  nwkr  the  Caiii.el  button  the  defjuilt  button,  iisi-  d  bta^e  byte  of 
SCI.  This  sets  the  wjond  number  to  t>l  (one  beep),  sets  bit  7  to  1  (draw  the  box), 
and  sets  bit  6  to  I  [the  defaolt  is  #2,  Cancc3). 

1'he  filter  procedure  used  by  iiu  aU'it  bos  i^  similar  to  th<"  one  deseribed  earlier 
for  dialog  boxes.  Pushins  a  0  viiliic  tells  the  illlictlon  to  ii.se  the  standard  filter 
proeedure.  It  cfinverts  tt  Return  keypress  into  the  click  of  the  default  button  in  the 
alert  box. 


REFERENCE  SECTION 

Table  RS-1:     The  Major  Functions  in  the  Dialog  Manager  Tool  Set  ($15) 


FujictUm    Slack  Descripiion  of 

Function  Name  Number    Parameters  Parameter 


Alert  $17  result  [W]  ID  of  item  selected 

AlertTemp  (L)  Ftr  to  alert  template 

FilterProc  [U  fir  to  Filter  procedure 
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Fttnctiim  \(ime 
CautionAlcrt 


Function  Stack 
Number  Parameters 


Description  of 
Parameter 


Close  Dialog 
DialogSelect 


DialogShutDowTi 

Di  sable  Dl  tern 

DlgCul 

DlgDdcte 

EnablpDIt<'iTi 

FiiidDJU'in 


CetDellJutton 


51A  result  [W) 

AiertTemp 
FillerProc  (L) 
$0C  TKfDialoR  {U 

$11  result  (W) 

Ev«ilRecord  (L) 
ThrDialdg  (L) 
IteiiiMilPtr  (L) 
$03  |no  iMranit'tcTs] 

S02  UseilD  (W) 

S39  ThoniaKig  (U 

ItenilD  (W) 
TheDialog  (L) 
Tht'Dialug  {D 
ThcPiaing  (U 
Tln-DiiiloR  (L) 
Tht  Diftlnj/  (L) 
ItemlD  [Wl 
result  (W) 
TheDialoR  [L) 
ThePnint  (Lt 
$.1,7  result  iW) 

Tln  Ditilog  ID 


£13 
S15 
$L4 

S3A 

$£4 


1 D  oi  Ltein  selecteti 

Plr  to  alert  template 

Pir  tn  filter  procedure 

Pti  to  diuJc)^  record 

BuKjleiUi;  enabled  item 
chosen? 

Pfr  to  event  re'C'ord 

Ptr  tii  sp^Cf  tVir  dialtjfi  ptr 

Ptr  to  space  fur  item  number 

ID  tag  fur  memory  allocation 

Ptr  In  diiilog  record 

ID  of  item  to  disable 

Ptr  to  dialog  record 

Ptr  tct  (tidlo^  record 

Ptr  to  dialog  record 

Ptr  to  dialog  record 

Ptr  to  dialog  record 

ID  of  item  tu  enable 

ID  of  item  3t  point 

Ptr  to  dialog  record 

Point  to  check  (global) 

ID  of  default  item 

Ptr  to  dialog  record 
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FiiitetUm  .Vuifif 

i'lI/lCdHft 

Number 

Smck 

Parameters 

Description  of 
Parameter 

CetDl  tern  Bos 

S28 

Plr  to  dialog  record 

Itt'liilD  {WJ 

ID  01  dialog  item 

IteinBoxPtr  (L) 

rtr  to  feturnecl  rcctungie 

Gct;Drtt>mTypie 

result  (W) 

Item  type  cikIc 

TheDialo^  (L) 

I'tr  to  dialog  record 

I1l-i]i1D  (W) 

ID  0]  dialog  itc!m 

S2E 

result  {WJ 

VaJue  OT  dJilo^  item 

Ptr  to  diaJoj;  ret^ord 

ItemlD  (W) 

ID  oi  dialog  itein 

GetlText 

$1F 

TlieDialog  (L) 

T^.        .1-1  1 

Pti'  t(i  didug  record 

UeinID  (w) 

ID  ul  dialog!  item 

Tho String  [U 

Ptr  to  result  string  s[]a<:e 

CelNewDlleiii 

SJj 

Ptr  to  dialog  record 

IlemTfTTip  (L) 

Ptr  ti>  item  template  space 

Ce  tNewModal  Di  alog 

532 

result  (L) 

Ptr  to  dialog,  rrcnrd 

DiaJiicTtinip  (L) 

■                  J'l          J.  ll. 

Plr  to  dialog  template 

Hii^eDIteiii 

TheDialog  (Ll 

Tit.      ■       J  -    1     _D  _1 

Ptr  to  diakig  record 

IteinJD  (W) 

lU  ol  dialcig  item 

IsDialogEvent 

resiill  (W) 

Boolean;  dialog-rd^tetl? 

EventHec-ord  (L) 

Ptr  tn  event  record 

Modal  Dialog 

$0F 

resull  (W) 

ID  of  selected  item 

FilterProc  {L) 

Ptr  to  filter  protedure 

NewDUem 

SOD 

TlieDialog  {D 

Ptr  to  dialog  rtfL-Ord 

IteiiilD  (W) 

Item  ID  number 

ItemRect  {LJ 

Ptr  to  item  rectangle 

ItpmType  (W) 

Item  type  code 

ItemDescr  [L) 

Item  descriptor 
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Function  Name 


Function  Stack 

iV  umber    Paramf  te  rs 


DescriptUm  of 
Parauufter 


NewM  odalDiaiog 


New  Model  essDialog 


Note  Alert 


ParamTpxt 


SellText 


SetDcfButttm 


IteraViilue  (W) 
ItcmFlag  (W) 
ItemCotorPtr  (L) 
$0A  result  (L) 

DBouiidsRect  (LJ 
DVisible  (W) 
DReJCon  {L] 
$0B  result  <L) 

DBnundsRect  (L) 
DTitlePtr  (L) 
DBehindPtr  (L) 
DFlaR  (W) 
URefCon  (L) 
DF  nil  Size  Ptr  (L) 
$19  result  [W) 

AlerlTemp  (L) 
FiltrrProc  [L) 
FsramOPtr  (L) 
ParamlPtr  (L) 
Param2Ptr  (L) 
ParamSPtr  (L) 
TheDialog  (L) 
ItemID  (W) 
SlartSel  (VV) 
EndSel  (W) 
TkcDialog  (L) 
DefButlD  [W} 


Item  value 
Item  flags 

Ptr  to  item  color  table 
Ftr  to  dialog  rfcnrd 
Ptr  to  dialog  rettiinfjie 
Boolean:  is  it  visiblei' 
Reference  constant 
Ptr  to  dialog  record 
E*tr  to  window  rectaHgle 
Ptr  to  dialog;  title 
Ptr  to  window  in  front 
Window  frame  bit  vector 
Reference  constant 
Ptr  to  zoom  rectangle 
ID  of  item  selected 
Ptr  to  alert  template 
Ptr  to  filter  procedure 
Ptr  to  '0  string 
Ptr  to  "1  string 
Ptr  to  "-l  string 
Ptr  to  '3  string 
Ptr  to  dialog  record 
ID  of  dialog  itern 
Start  of  selection  range 
End  of  selectiun  range 
Ptr  to  dialog  record 
ID  of  new  defaidt  button 
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Funciion  Name 

JV  ii  •!     r/i  ti 

Nutnher 

J  LCiC  K 

Parameters 

Parameter 

SetDltt-mBns 

$29 

TheDialos  (L) 

Ptr  tn  diLiln^  rpcord 

ItemlD  (W) 

ID  of  dialoj^  item 

ItemBoxPtr  (LJ 

Ptr  to  new  rectansle 

SetDltemType 

$27 

IteniTyjjf  (W) 

Xcw  item  type  code 

TkeDiiilog  (L) 

Ptr  to  dialo^r  record 

llemID  (W) 

ID  [if  diaJng  item 

SetD  I  tern  Value 

$2F 

rtemValue  (W) 

New  value  lor  item 

ThcDialog  (L) 

Ptr  to  dialog  record 

ItcjnID  (W) 

ID  of  dialog  item 

SetlText 

TheDialng  fL] 

Ptr  to  dialog  record 

ItenilD  [W) 

ID  of  di^og  item 

TheString  {L) 

Ptr  to  new  text  strinR 

ShowDItein 

$23 

TheDialog  [L) 

Ptr  to  dialog  record 

IteinID  (W) 

ID  of  dialog  item 

Stop  Alert 

«18 

result  {W] 

ID  of  item  selected 

AlertTenip  [L) 

Ptr  to  alert  template 

FilterPrac  (L) 

Ptr  to  filter  procedure 

Table  RSf-2j     Dialug  Manager  Error  Codes 


Error 

Code  Peffcription  of  Error  Condilioti 

E150A  Tlie  item  type  cud*'  is  invalid. 

^il50E  The  Newltem  call  was  uri-^ucccssfiil. 

$150C  The  specified  item  was  not  Found. 

$1.'jOD  The  active  window  is  not  a  mod^  dialog  box. 
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Boxes 


Table  Kfi-^:     L'st-fiil  FuriL-tjuiis  in  ill-.-  LiiifEdit  Toiil  Si-t  <$141  

Functiftn       Stuck                    DefiL-rifition  of 
Funclivn  Numc       Numher  Parameters  Fargmeter  

LEShutD<JWTi  S(.^3  [nn  parAmeters] 

LEStartup  S02  L'seriD  (W)  ID  tag  for  nienn)r>'  allcfLiilum 

DPAddr  (W)  Addrt-ss  of  ]  pd)i.e  in  hank  0 
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Listing  fi-l:     Deflninff  and  H;indlhi;!;  a  Motlal  Otaloy  Bnx 


Madal  START 

Lining       Die  gDa  t  a 

;  Create  the  modal  dia.iog  hox 


PHA 
PHA 

Pu  5hP  t  r-  DialogBojt 
_GptNewModalDialog 
PopLong  TheDiaiog 


;SpflCtf  foi"  result 


SoModg I 


PHfl 

PushLong  «a 
PLfl 


J  Bpac^  for  r  esu 1 1 
latandard  filter  procedure 
iMandle  dcliuity  in  box 
;Cet  the  ttem  selected 


CMP 
BEQ 


*1 

GoHodfl 1 1 


;DK  button? 

;  Ves  ,   5o  branch 


CMP  *2I) 
BCC  Tgggle 


;Yes,   sa  branch 


j    If  we   re^ch  here,    it  must   be  e   redic  button. 

;  When  you  turn  one  radio  butloii  on,  all  other  family 
;    member  ^  are  turned  off  au  toma  t  i  ca 1 1 y ; 


QoPladall 


PushWord  *t 
PushLorg  TheDialoc 
PHX 

^SetltemVaUe 
MP  GoModol 
ANQP 


iTurn  selected  radio  buttcn  on 

■;PLi3h   selected   it  eim 
;RedraM  with  new  value 
i  Oq  bsck   la  dialog 


Here    is  where  you  would   inspect   antt  5ave   the  netting;  of 
all   the  uarjable  parameters  so  that  you  can  u^e  them  in 
arrother   part   o(    the  program.    Use  Ge  1 1 1  emVa  I  u  e  and  GetlTeict 
lo  determine  the  value  for  each  item. 


PiishLong  TheDialog 
_Clo5cDia 1 ag 


i&e t    rid  of  dialog 
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;    Toggle    the   netting    of    the    chect    baX : 


Toggle 


ANDP 

TAX 
PHX 

PHA 

PushLong  TheDiaiog 
PHK 

_Get I t  emVg I  up 
PLfl 


#$01 


PLX 

PHA 

PuahLong  TheDialog 
PHX 

_Set 1 temVa lue 
JP1P  GonDdal 

END 


;SHve  TD 

iSpace   fcr  result 

iPiiah  item  ID 

;Gct   carrent  valjc 

iJoggli^  value  bit 

;Get    JD  back 
•,Hew  value 


iredraw  with  vhIup 
;D^ck   lo  dialog 


DlcgData  DflTfi 
TheDialog  DS 
;  Dialog  Template! 
DlBlogSox  DC 


I '30. 1  DO  ,1 35,<65' 


DC 

DC 

14 

«0' 

DC 

1  4 

'  Dl temi  ' 

DC 

'Dltem2' 

DC 

1 1 

'  Dl Tffm3 ' 

DC 

14 

'DIt«m4' 

DC 

M 

'  DI temS ' 

DC 

M 

•DI CffmGi 

DC 

M 

'DI  ten.7' 

DC 

H 

'D 1 temB' 

DC 

lA 

'Dl tem9' 

DC 

M 

'Dl temi 0' 

DC 

M 

'Dlteml 1 ' 

DC 

14 

'Dllemi 2' 

DC 

14 

' Dl temi 3' 

DC 

14 

'DIlemt4' 

DC 

14 

" DI temi 5 ' 

DC 

11 

' DI temie* 

DC 

M 

'Dlteml?' 

DC 

'Ot  temi B' 

i  True  =  visible. 

;  ref con 


Hefereixcc  Section 


DC  I4'Dltemlg' 

M  l4'DUem20' 

DC  I4'Dltem21 • 

DC  1 4 ' 0  ' 

Dlteml  DC  I2'l'  illem  ID   [1    -  default  bution) 

DC  12 'SO , 300  . 1  00 ,350 '      fDisplay  rectsrgle  (local) 

DC  JS'BiiltoTiItem'  ilte*  type  code 

DC  H 'Butto-nStr*  iName  of  button 

DC  1?'C'  ^Nol  used 

DC  12^0  "  ;  I  lem  f  Ug  (default) 

DC  H'Qf  iColor    tablE  plr  (default) 

BultonStr      STB  'DK' 

D[lem2  DC  12'?^  ; Item  [D 

DC  I  2  '  5  ,90  ,  I"!  .  300  '  ;Dl5play    rectangle  (local) 

DC  l2'StatTe)ct*I8000'     ;Item  type  code  (disabled) 

DC  l4'Slatlf  ;Etalic  text  string 

DC  l£'0'  litem  value  (uiiusEd) 

DC  l^'O'  ;ltem  flag  (defaLlt) 

DC  M'O'  ;CDlQr    table  ptr  (default) 

Stfltl  STR  'C  nmiimn  ications    Pararrelere'  -Static    teit  string 

D[  terr3  DC  I2'3'  ;  I  lem  ID 

DC  12'1  7, 10,27,10D'  -.Display  rectangle  (local) 

DC  I2<StatText*teO00'  ;[tem  type  code  (disabled} 

DC  H'Stgt?'  -.Static  text  atring 

DC  l?'0'  iltem  value  (unused) 

DC  I2'Q'  ;  Item  flag  {dsfauU) 

DC  I4'0'  iCglor  table  ptr  (default) 

SlatE  STB  'Baud  Bate:'  iSlalic   lent  string 

Dl tam4  DC  I2'4'  ; I  tern  ID 

DC  12' 1 7, 1  DO  .27,1GQ  '  ; D i sp I  ay  r ec ta n g 1 e  fl&cal) 

DC  I2'Rdidiolteni'  ilt^m  type  code 

DC  H'Radioli  ;  Name  of  bullon 

DC  I2'a'  ;V^tlu?:    0   =   Qff   /   I    -  on 

DC  I2M  '  ;Baud  rate  family 

DC  M'O'  iCoJor   table  ptr  (default) 

Radiol  STR  '  300  ' 

DItemS  DC  12'^'  litem  ID 

DC  12M7.1SO,27.EG0'  iDispiay  rectangle  (local) 

DC  T2iRadioltem'  ;Item  type  code 

DC  l4'Radni2'  iName  of  button 
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DC 

12'  1  1 

;'i^aluip:   0  ^  off  /  1    »  on 

DC 

I2'1  ' 

; Baud  rate  f am  1  y 

I  d  p  n  1 

^'L'UJUr        ^DULt     LILT  ILIff^iaUILJ 

□  1  oc 

C  T  □ 

t  \  'inn  I 

r  T  *  jt.j^c 

UL 

I  c  b 

;  1  iflin  1  u 

DL 

;Qispiqy    rectangle  flocal) 

BC 

I  S  '  Rad  Lo I L^m' 

;  I  Ism  type  code 

OC 

j Name  of  biitton 

DC 

l^^fllue:   0  "  off  /   }    '  a-n 

DC 

12'  1  1 

[Baud  rate   fern  Ly 

I  d  1  n  1 

1  1  u 

KflO 103 

CT  H 

Ul I  em  ^ 

UL 

1  -5  i  "7  ( 

;  1  I  en    1 U 

; Display   rectangle  (ioEial) 

PC 

12<StfltTeKt*ieOCQ' 

litem  type  code  [disabled] 

DC 

I<)'5tflt3> 

;  Stdtic   text  string 

DC 

litem  value  (gnuSed) 

DC 

12'!)' 

J  tern  f lag   [defaui  t  ) 

1  4  I  n  ' 

■Tnlnr     t^^hlf^    nTr  fHf>f^iilt^ 
liL^DlUr       L0LJ1C     IJLr  ^UCHOUlhJ 

t;  t  a  1 T 

^  I  B  1  J 

■         la     n  1  f  G  ■  I 
IL'HlB  DiLai 

U  1  1  ejT  B 

UL 

; 1  I  em   i  U 

UL 

1  C    £  J  ,  p  ULP  ,       ,  1  3  U 

^Display  rectangle  (local] 

DC 

1 2 ■ Rad !□ 1 tem' 

; 1 t em  t ype  code 

DC 

iName  of  button 

DC 

12'  1  f 

■.Value:    0    =    off    r    1    '  OTi 

DC 

12"2' 

; Da ta  bi t  9  f  ami Ly 

DC 

i  ^  '  0  ' 

;CQlgr    table    ptr  (default) 

Pari  1  nA 

1  a  r 
o 

i  £  ^ 

-  1  f mm    T  n 

1  1   L  E  111      i  U 

DC 

;Di5play   rectangle  (local)- 

DC 

]2iRadiolleni' 

; i  t em  t ype  code 

DC 

i  Name  of  but  t  on 

DC 

12f  0  • 

^Value :   D  ■  off   f  1    ■  on 

DC 

; Da  ta   b i t  ^    f  am i 1 y 

DC 

M'O  ' 

;Color  table  ptr  (defaiilt] 

Bad  1 oS 

STR 

1  7  h 

D!tem1 0 

DC 

;  1 1  em  ID 

DC 

12'4-t  ,  10,51  .1  OQ  ' 

;Display  rectangle  (iocalj 

DC 

;Item  type  code  (disabled)' 

DC 

H  'StaM' 

;Glali.c:    text  string 

DC 

12'1  ' 

;llem  value  {unuaed) 
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DC 

I2'0' 

jltem   flag  (default) 

nr 

UL 

i  A  1  ft  t 
J  1  ■  U  ' 

;Color   table  ptr  {default) 

S  ta  1 4 

SIR 

■Stop  Bit^.;  ' 

;Statlc    tent  string 

Dl ttml 1 

DC 

12'  11  1 

;]tem  ID 

DC 

12  »  41  , 1  00 .51  , I  50 ' 

'.Display  rectangle  [local) 

DC 

12'Hadioltem' 

J  I  tern   type  code 

DC 

14  * RadioG' 

;Hdmc  of  huttan 

DC 

12M  ' 

[ Ua lue :    0   =   off   /    1    «  on 

DC 

12*3' 

;5tcp  bits   f ami  1 y 

UL 

T  J  T  n  1 
J  S  U 

iColor   table  ptr  (default) 

C  T  D 

'  1  ' 

D  r  temi 2 

DC 

12M  2  1 

!  1  tern  ItJ 

DC 

,  1  50,51  ,2C]0f 

jDisplay   rectangle  (local) 

DC 

1  2 ' RadL  0 1 tem' 

1  1  I  em  type  code 

DC 

; Name  of  buttor 

DC 

I2I0I 

sValiie:    0   '    o+f   /    1    =  on 

DC 

1213' 

;3 1  op  bi  1 9  family 

1  A  1  h  1 

;LolDr    table  ptr  (defaull) 

I^a □  i  CI  / 

CT  □ 

b  1  K 

t  ^  1 

DI temi 3 

DC 

12 ' 1 3' 

litem  ID 

DC 

12 '53, 1 0 ,B3 , 1  00  ' 

;Di5plfliy  rectangle  (Iccal) 

DC 

litem  type  code  (dLsabled) 

DC 

H  'StatS' 

iStatic    teict  string 

DC 

litem  value  (unused) 

DC 

; 1 tem  flag   ( def 1 t ) 

IbOlor    leDls  pi-^  [oetdLiil) 

tit  =  *  e: 

C  TD 

'  Pa  r  1 1  y  :  ' 

;Static  text  string 

D 1 1  em1 4 

DC 

I E  '  1  4 ' 

;  1  tem  ID 

DC 

l2'53,10t),53,lBQ» 

^Di^play  rectangle  (local) 

DC 

1  2  ■  Radioil  t  em  ■ 

;  1  tern  t  ype  cod« 

DC 

l4'Radio8> 

iName  of  button 

DC 

12'  1  " 

; 1 ue ;    0    "  off   /    1    '  on 

DC 

13141 

; Par  1 ty  f ami  1 y 

DC 

M'O' 

;Color   table  ptr   (default  ) 

STR 

DC 

12  M  5  ' 

1  I tem  ID 

DC 

[2'S3.ieO,S3,2Ba' 

;Di5play  rect.angle  (iocall 

DC 

r^'ftsdiortem' 

;  1 1  em  type  code 

DC 

H  <Rfldio9' 

i  Name  of  bu  1 1  oti 

DC 

IZ'  0' 

;Valae:  0  ■  off   /   1    =  on 
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DC 
DC 


IS' 


4' 


; Pari  ty  f ami  1 y 

iColor   lable  plr  (default 


Rsdi 

5TR 

'  Even ' 

DC 

12  ME' 

Item  ID 

DC 

13'S3, 250  ,63,340'        ;Di5play   rectsTiqie  (local) 

DC 

1  2  'Radio  1  Iprn  1 

1 1  em  t  ype  code 

DC 

li'BadiolOi                  iHame  of  buttor 

DC 

12  '  0  •                                    ;V^Ue  :    0    =    of  f    /    1    -  on 

DC 

1 2 '1 '                             ;Pflri ty  f am L ly 

DC 

H'G'                             jColop  table  ptr  (defajUJ 

Snri  \  n^  0 

•□dd' 

Dl temi 7 

DC 

12'  17' 

Item  ID 

DC 

I2'&S,1Q,7S,ISC1' 

Display  rectangle  (local) 

DC 

1  2  'Check : lem' 

Item  type  code  Idisabled) 

DC 

H'Check^  ' 

Static    teic  I    St  r  1  ng 

DC 

12'fl' 

Value:   D  ■  of f  /  1    "  on 

DC 

12' 

1  tern  flag  (default  ) 

DC 

14'  D  + 

Color   table  ptf    (def au  It  } 

Check  1 

STR 

"  Fi  1  tar ' 

DltemlB 

DC 

JEMS' 

Item  ID 

DC 

12  '65, 120.75 ,230 ' 

Display  rectangle  t^o^al) 

DC 

12*Chcckltemi 

Item  type  code  (disabled) 

DC 

14  '  Checks ' 

Static   text  itring 

DC 

12'\  ' 

Walue;   0  =  off  /   I    =  qti 

DC 

12  '  0  "                             ; 1 lem  f lag   [defaul t  ) 

DC 

14  '0' 

Color  table  ptr  (default) 

Check? 

STR 

1  KDH/KOFF' 

Dl leml 9 

DC 

12'  19^ 

Item  ID 

DC 

1 2  '65  .230 , 75 ,340  1 

Display  rectangle  (local) 

DC 

If 'Cn^cli  1  I^m' 

Iteim  type  code  (disabled) 

DC 

M'CheckS' 

Static    text  airing 

DC 

12'  D< 

Value:   0  =  off  /  1    =  an 

DC 

12'  0' 

Item  flag  (default] 

DC 

11 '  D  ' 

Color   table  ptr  [default) 

Chect3 

STR 

'Line  Delay' 

D]t=m20 

DC 

15'20' 

Item  ID 

DC 

[2'79, 10  >89,1  IS' 

Display    rectangle  (local) 

DC 

12  'Stat  Te>tflSO0O  ' 

, I tem  type  code  (disabled) 

DC 

14  '  5talb' 

,Slalic    text  string 
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DC 
DC 
DC 


■[  1 1  em  va  1  ue  (  unuaed  J 
■  Hem  flag  {default) 
iColor   table  ptr-  (default' 


Stfl l&  STR  ' Download  File:' 

DC  12  '  77  , 1 20 ,90 , ?75 ' 

DC  l2'EditLine*»B[)G0' 

DC  l4'EditStrin9' 

DC  I?'1S' 

DC  1 2 ' 0 ' 

DC  14101 


[Static    texl   5t  r 1 ng 
!ltem  ID 

■,Diaplay  reclargle  (local) 
litem  type  code  (diaabled) 
lEditable  text  itfing 
;P1aidimum  string  length 
; Item  flag    [default  } 
iColor  table  ptr  (default) 


EditStrmg  SJH 


' Message  5 ' 


END 
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This  IB  ft  custom  filter  procedure  for  ModeilDlalcig, 
Qn  entry,    the  stack    i5   coTifigured  as  follows; 


resu I t : 
theDi a  1  eg : 
t  heE vent i 
i  temNi  t : 
r  elu  r  nfiddr : 


MDRD 
LONG 
LDHC 
LDHG 
3  BYTES 


Return  a  TRUE  result  if  ModalDlalog  15  la  exit  with  ilemHit 
or  a  FALSE   result    if    it    15   to  proceS!    the  event  itself. 


To  use  a  filter  procedure,  pa^?  a  pointer  tu  i 
Set  the  high  bit  of  the  poifiter  to  daisy  chain 
filter  which  h&ndlea  keyboard  ed i t i ng  commands 
fietkirn  press  to  a  glict  of  the  default  button, 
do    th J  S : 


;    to  FlodalOialog, 
to   the  standard 
and  canver  1 5  a 
Here  '  s  haw  t □ 


PH6 
LDA 
□  RA 
PHfl 
LDf\ 
PHft 

_MDdalDia 1 og 


/"F  1 1 1 erProc 
'F 1  1  terPr  OC 


; Address  high 
; Set  high  bit 

;Address  low 


This   particular    filter  effectlVBl/  removes  all  nonediting 
conlroi  characters  so   they  won't   appear  as    iTiversc  queation 
marts    in  an  EditLine  item. 
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FilterPrac  BTfiGT 


;   these  art  direct  page  addrcBaes  after  PHD/TSC/TCD: 


□  ItJDB  EQU  (01 

□  IdDP             EQU  nidCB'-I 
ReturnfldtJr  EQU  UldDP*£ 
ItemHit           EQU  ReturtlAddr*-3 
IheEvent       EQU  iterrHit*4 
IheDialag     EQU  theEvBTlt^'t 
re suit           EQU  theD  ta I og*1 

PHB  ;5ave  data  bank  register 

PHK  jfliiau'  flb5cliit*  addr«49ing 

PLB 

PHD  iSave  direct  page 

TSC 

TCD  lASign  d.p.  uiilh  atecl: 

LDA  [IheEy^enl.]  ;&et  "wtint"  from  event  record 

CMP  *3  ;<ay  down  event? 

BNE  Exit  ;Na,   =o  branch 

LDfl  [theEuenl],r  ;&et  ASCII  code 

AND  »»Q07F  ;Corvert   to  4ld  ASCII 

CMP  'lOOEO  jConlrol  character? 

BC5  Etit  ;Ha,   50  branch 

iFllter    all   cantrol   chars,    except  CR  or   dues  used  by  LincEdlti 

LDX  »Q 

CtrlLook       CMP  CtrlTable.S  ;Is   it   in   the  lisf 

DEQ  Exit  ;Ves,  50  branch 

INX  jMove  to  next  entry 

Itii 

CPX  TbiSize  ^fit  end  of  table? 

BNE  CtrlLook  (No,    so  branch 

LDfl  *0  ;Convert    to  "null"  event 

STfl  [theEventl 

E»  I  tl  STfl  reSul  t 

PLD  ■,  Res  tore  d.p. 

PLB  ^Restore  data  bank 
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Discard   input   pararriBtera  end  move    stack  up  by   12  bytes: 


LDfl 

2,S 

STB 

M,S 

LDPi 

1  ,S 

STfl 

13, S 

T5C 

CLC 

ADG 

#12 

res 

RTL 

;  This  Iflhle  contaiTis  all  th«  control  characters 
;   that  are  specially  treat ed  by  LineEdLl,  and  CR. 


CtrlTable     DC  PlOG'  iDelele  ch^r  bclo*  cursor 

DC  I  '108'  -fLcft-Brrow  (backspace) 

DC  r ' JQ9'  iTab 

DC  ['lOD'  iCIf 

DC  T'llS'  iRlght-arrou  (forward] 

DC  ['$18'  TControlU    (erase  line) 

DC  I'I19'  ;CoTilrcl-Y    (ct*or    tg  £DL) 

TblSlic         DC  [ ' TblSize-Cl r ITabie  < 


END 

Listing  8-3;    The  CheffeHit  Subroutine  to  be  Called  When  MttdalDialog  Returns 
A  Ckec'k  Biix  lt(;m 


■C^n   CheckHit  in  response  tc  a  hit   in  a  dialog 
;   check  box.   CheclHit   charvgea   the  value  of  the 
;    item  from  3   to  1    (if   it  is  off)  or  frofli  1    to  Q 
;    (If  it    15  on)  . 

-,Ui  cTitryt   A  ccntain^   the   ID  number  of  the 
;   checl:  box   item  in  quastioTt. 

jTheDialog   ls  a  dialog  pointer  itored  in 
;   the  OlobalData  data  segmcTit. 

CheckHit  STftRT 

{Jsing  OlobelData 

TAX 

PHJ  ;Save  ID 
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PHft  ;Space  fcr  result 

PushLoTig  ThcDialog 

PHK  ;PLiah    item  ID 

_GBt 1 lemVal ue 

PLfl 

EQR  •'JOI  i  Invert  value  hit 


PLX  i&et    ID  back 

PHA  ;New  value 

PiiahLong  TheDialog 
PHX 

_Se  t  I  ternVa  lue  vredrauwith  newvalue 

RTS 


END 


U.>iling  S-4:     The  RadinHir  Siihrniitinr  to  he  Called  When  MiidiilUidliig  Rctunis 
;i  Radio  Button  Item 

Call  RadioHit    in  rpsponse   Id  a  hit    m  a  dialog 
rad:io  button.   RadioHit   aets  the  value  of  the 
vtem    to    1.    This   cau^e^    ail    ether    family  member^ 
to  be  turned  off . 

Cti  entry,        contains   the   ID  number  of  the 
radio  button   it  em   in  question. 

TheDialog   i?  a  dialog  pointer   stored  in 
the  GlobalData  data  segment. 


RadlaHit  ST^RT 

Using       Cloba 1 td 


TPK  ;5ave  item  ID  in  K 

PughUlor a  *  1  ;  1    "  Qm 
PuahLong  TheDialog 

PHX  ;Puah    item  \D 

_S  e  t  1 1  entVa  lue  ;redrawwith  neu  ualue 

BIS 
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Listing  S-5:     How  To  Creiitc  n  Mmit-les^  Dialug  Box 


Create  a  madcless  dialag  box; 


Mod  eL  es  a 


START 
Using 


;  Space   for  reau  J.  I 


PHA 
PHA 

Pu5hP t r  D 1 AlogRect  ;Conlerl  rectangle 

PuahPtr  DlogTitle  (Tille  -of  window 

PushLong  (--I  ;Ptr   to  window  in  front    f-''    *  top) 

PushWordl  *X  1  1  0  0  0  0  00 1  Ol  000  0  D  iffaine:  close,  title,  drag,  viaibl 
PuahLong  •{)  ',  ref  con 

Pus  hL  org  #D  ^iaoih  rec  tangle  (O-defaull) 

_Newriodele9sDialog 

PopLong  TheDialog 

PuahLong  TheDialog 
PushPLr  Dlleml 
GetHewD I  tern 


PushLonc 

TheDialog 

PiiBhPtr 

Dl  teffl2 

Ge  t  NewD'  1  t  em 

RTS 

EMD 

DlogData 

DATA 

Ci  a  1  D^Rcc t 

DC 

1  '30, SO .1  DO ,425' 

DiagTit le 

SIR 

'Scargti    for  Text' 

;  1 1 1 1  e 

TheDia 1 nq 

as 

jPoLnter    I0  modelesB  dialog 

;  Dialog  Template: 

CItemI 

DC 

12'  1  ' 

;[tem   10  (1    ■  de fault  button 

DC 

J2  '■40  , 1  10  ,60  ^?50  ' 

;Di5plfly  rectangle  (local) 

DC 

[2  'Button  1  tern' 

;  1  tern  typ^  coide 

DC 

tl'HultonSlr ' 

;  NaniE  of  bu  t  tan 

DC 

[2*0' 

;NDt  uaed 

DC 

iS'Q' 

J  1  lem  flag   ( def aul t ) 

DC 

M  '0' 

;Colcr    lahle  ptr  ^default) 

BjltorStr 

sre 

' Beg  J  r  Sear  c  h  ' 

Dl  tem2 

DC 

I2'2" 

;Itern  !D 

DC 

1  2  '  1  7  , 1  00 , 30  ,320 ' 

jDtaplay  rectangle  {loca,!} 

DC 

1  2  '  Edi  ILine*  »90QO 

''    litem    tyrpe    code  ^disabled) 

DC 

M'EditString" 

; Editable  tcKt  string 

DC 

12'ZQ ' 

;riBxiniijm  5trLiig  length 

DC 

;  Item  f laq   (defduil  ) 

DC 

II'D  ' 

iColor    table  ptr  [defaall) 

Edi  tStr-  ing 

STR 

II 

;5tart  with  null  siring 

END 

Listing  S-6: 

How  To  Handle  EveiUs  in 

Modpless  Dialog  Boxes 

■-,  Use  this 

type  of 

event    loop  when  a  modeleas 

;  dialog  may  be 

1 1  ve  . 

STAftT 

U5  1  ng 

PHfl 

PushWord  'IFFFF  lAH  events 
Pu5hPlr  TaskRec 
_Ta5kMa  s t  cr 

PHA  1  apace  fpr  result 
PushPtr  TaaiPec 

_  1 1  ogEvent  ;Ia    it   for  modeless,  dialcsg'' 

PLA  ;Get  Booleari 

BEO          EvtLoop!  ;Nd,   so  branch 

;    If   the   keypress  was  a  menu    item  keyboard  equiv'alentn    turn  the 
;  menu  h  1  gh  1 1  g<n  1 1  ng  off,   D  ia  logSe  lee  t  doesTi't  do  this  for  yon. 

PLfl  the  TastMaster  reauit 

CMP           'wlnPleriuBar  ;5tgrdard  menj  item'' 

BEfl           TltieDff  iVea,    ao  fix  menu  ttUe 

CMP          /wlnSpecial  jSpeciai  meriu  item? 

BHE           DoModelesa  iNa,    go  do  nothing 

TitleCff       PushWord  fC  ; H i gh 1 1 gh 1 i ng  off 

PLishWord  Taal:Date.'2  -.Get  menu  ID 
_Hi 1 1 tcMenu 

LDA           Ta5  tDa  ta  ;  &e  t  meiru   1  tern   1 D 

CMP          '256  jSpeeial  editing  item? 

BCC           CoMode 1  ess  I^sa,    ao  give   it    to  D lalogSelec  t 

;  Handle  nanediting   keyboard  equiualenta  here, 
j   then  return  to  the  event  loop. 

BHL  EvtLdop 

DoMods  1  eaaPHPi  (spaceforBfloleanreauIt 

Fu^hPtr  TaakRec  ^Task  record  pointer 
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PushPtr  DlogiActlwc  lOifllog  pcinter  returned  here 

PuahPtr   ItemHit  ;Item  number  ceturntd  here 

PLft  jWas    it  handled? 

BEQ  EvtLoDp  >Nd,   90  brarch 

The  event    js  dialog-related   if  we  reach  here.   DoDlalog   15  a 
Bubrouline  yau  woLild  write   to  handle  dialog  activity.    It  can 
get   the   relevant   dialog  pointer    frcra  DlogHctlus  and   the  Item 
number  from  ItemHil. 


JSR  DoOiaicg  ;Haiidle  dialog  activity 

3RL  EvtLoop 


Etf ILoop! 

PLfl 

iGel  TflilMflster  result 

i 

[hondlc  TaskMflster  reauH 

in  uaual  way] 

EvtLpop 

lElack   to  event  loop 

DoDia log 

AHOP 

[thka 

subroutine  handles 

dialog 

ae lec  tlona  i 

RTS 

EMD 

Dl ogDa  ta 

DATA 

DlogAclivc 

D& 

ItemHU 

D5 

2  . 

£ven  t  Rec 

AMOP 

j Evert 

record 

Mhat 

OS 

; Evert 

code 

nesaage 

DS 

; Event 

reaul t 

kifhern 

D5 

;Tict5 

Since  startup 

Mherc 

; Mouse 

locat 1  on    (global ) 

Mod  I f I er  s 

D5 

;SlBtua 

of  modifier  fceya 

Tas  h[Data 

DS 

; To5 IMa  St  er   da  t  a 

Tab  ktlas  fc 

DC 

H'lOOOOIFFF' 

^TaakMaater  handles  all 

END 


LisHng   8-7:    The  Type  of  StibroiiCine  a  ProRrain  Should  Call  To  Hwdle  Editing 
When  a  Modeless  Dialog  Bos  is  Active 

;  Thia  subroutine  handles  special  eilit  itema  for 

;  modeless  dialog  boxes.    If  the  carry  flag  la  set  on 

j   exii,    the  edit  conrhmand  was  handled. 

■■,  The  pointer   to  the  dialog   ls  stored  at  TheDialog. 
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DaEditiTig  flHDP 


J  Checl;   ta  see   if   the  modeless  dialog  box   15  ijcliue: 

^Get  pointer  to  active  wind ow 


PHA 
PHfl 

_Fron  tWi  ndoui 
PL  A 
PLX 

CnP  ThcDialog 
BME  NoDlogEdit 
CPK  TheDialog*2 
BNE  NoDlogEdit 


^Campore  active  window  wltf^ 
1    did]  O'^  window. 


iPaaa    control    to    the  appropriate    edit    item  haTidler: 


SEC 
LDfl 
SBC 

■flSL 
TAX 
JSR 

SEC 
STS 

NoDlogEdit  CLC 

RT5 

Edit  Table 


Ta^kDeta 
A 

(EdLtTable.t;) 


;Get  menu  ID 

;Conuert   250  254   to  01 

,xZ  to  s Lep  inXa  tfib ic 


;SE:C  means  "was  h-andled" 
;CLC  means  "not   for  dialog" 


DC 

I 

f DUndo ■ 

;  1  lem 

[Undol 

DC 

I 

fOCut ' 

;  1  tern 

251 

fCut) 

DC 

I 

' DCnpy ' 

i  1  tern 

ZS? 

[Copy] 

DC 

I 

>  DPaste ' 

;  1  tem 

253 

[Paste) 

DC 

1 

'DClear' 

litem 

E54 

(Clear) 

DUndo 
DCut 

DCopy 

□Paste 

DC  1  ear 


Push  Long  TheDialog 

_DlgCij  t 

RTS 

Pu^hLong  TheDialog 

.DlgCopi- 

RTS 

PushLong  TheDialog 

_01gPa5te 

RTS 

Pij5hLang  TheDiatog 

_DlgDelete 

RTS 


;[ther"e   la  no  standard  uTida| 
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Listing  8-8:     Defining  and  Handling  an  AltTt  Bux 
;   Bring  up   the  .alert   box  ard  wait   for  a  button  push: 


Pol^  ierl 

START 

i)i  i 

IsrtData 

PHfl 

PL45hPtr 

AlertQox 

P  LishLon 

fliert 

PLA 

RTS 

AlertData 

DATA 

i    Alert   box  template: 

Aler  t  Bo  jc 

DC 

1     DU-p'U|   I  £v  If  t  U  ]J 

DC 

1  1 

cc 

1 4 ' (C3C2C1 ca ■ 

DC 

H ' fllerl I temi  ' 

DC 

H'fllertltBm?' 

DC 

H 'filer  Utem3' 

DC 

H  IQ  ' 

i^ler  1 1  tem1 

DC 

DC 

I2'30.80,50,140' 

PC 

12 ' But tonl tem' 

DC 

M'DKText  ' 

DC 

]2'0' 

DC 

I2'0' 

DC 

H  '0' 

DKText 

STR 

^OK  ' 

Altr t I temS 

DC 

12'2' 

DC 

DC 

l2'Buttonl tern' 

DC 

H'CancelTeKt  ' 

DC 

|£i(|i 

DC 

\2>0' 

DC 

M'Oi 

CaTice  ITex  t 

STR 

•CflTiccl  ' 

Aler  tl l^mS 

DC 

DC 

Q .S0,£E,32D" 

DC 

I?'StatTej(t'»BDQO 

DC 

M'ElalStr  jing' 

DC 

DC 

DC 

M'O' 

;^p^ce  for  reault 
;D-de-fault   filter  procedure 
iOet   Item  ID 


;fllert 
;  Alert 
;  St  age  5  by  t  es 
; Po inter   to  i  t em 
; Po  IF  t er  to  it  em 
;  Po  In  t er   ta   it  em 
^  Tormina  t  o  r 


*1 
*3 


-.Item  ID 

■.Display  recta ngle  (local) 

j  1  tem   type  code 

;Nanie  of  ■button 

jltern   valu?    {oii  ) 

;  I  tem  flag   (def eul t ) 

; Color  lahle  ptr   ( def aul t  J 


litem  ID 

[Display  rectangle  (local 
jiteffi  type  cede 
;  NflfTi*    ai  bLitton 
; I ttm  va lu  e   ( of f  ) 
; I lem  f lag  { defaul  t  ) 
jColor  table  ptr  (default) 


Item  ID 

Display  rectangle  (local) 

; 1 1  em  t  ype  code   ( d 1 anbled ) 
Stat  ic    test  string 
Itern  value  {unused] 
Item  flag  (default) 
Color  table  ptr    [default  ) 


;  "0  15  a  pUcehoIder  for  a  filenaffie  (LJ^e  ParamTcict  to  fill  It  in). 
StalString  STB  i  Do  you  i«anl    to  erase  "0"      -Static   text  string 

END 
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CHAPTER  9 


All  about  Desk 
Accessories 


Desk  accessories  ure  program";  (iiMially  small  utililiesl  thai  reside  in  memory  at  the 
same  time  as  a  priinarj'  t;s  applifritiim.  K'  the  application  is  properly  designed,  a 
user  can  taJl  up  a  desk  accessorv'  at  any  hme,  use  it,  return  to  the  applieaticm,  and 
continue  on  as  if  the  apphcatinn  had  never  heen  interrupted.  It  is  not  neeessary  to 
restart  tlie  applicatioti  from  the  be^innin^. 

Popular  desk  acwssories  are  pruj^rams  that  provide  features  that  few  applications 
support  directly:  a  calt-uktor.  note  pad,  clock,  and  appointnient  {.-alendar,  for  ex- 
sniple^ 

The  GS  supp<jrts  two  types  nf  dejik  acTtssorie-i:  classic  desk  aecessories  (CDAs) 
and  nrw  dcsV  utx'eKiories  (NDAi).  As  will  be  discussed.  CDAs  iU^e  available  to  any 
appllcatum  but  NDAs  wurk  ojdy  with  app]ica.t!uns  whiuli  take  advantage  of  the 
desk"tnp  environment.. 

To  call  up  a  CDA,  press  three  krys  oti  the  keyboard  simultaneously — Crjntrnl- 
OpenApple-EsL-.  Ttiis  Lanses  an  interrupt  signal,  whieh  the  GS  services  hy  clearing; 
the  text  screen  and  displaying  a  menu  ci>ntainins  a  list  of  the  names  of  up  to  fourteen 
CDAi  to  ehonse  iiroin.  You  tan  activate  li  speeihe  CDA  by  using  the  arrow  keys  to 
lii(^hliKlit  the  CDA  name  and  then  prcwin;;  Heturu.  There  are  two  standard  CDAs 
in  ROM:  the  Control  Panel  (used  to  ponfigure  the  system  hardware  and  set  pref- 
erencfst  and  the  Alternate  Display  VStide  (u,sed  to  enablt;  or  disable  software  shad- 
owing of  (he  secondary  tt'st  siTcen  (nun  S8ttO  to  $BFF). 

You  can  access  the  CDA  menu  any  time  65816  interrupts;  are  nut  diiiihietl  [with 
an  SEI  instruction),  which  is  most  uf  the  time.  Thus.  CDAs  can  be  used  with  .my 
GS  (ipplicatioii,  inchifliii^  traditiunul  lie-style  applications  and  the  new -style  appli- 
cations that  work  in  the  desktop  enviromnent. 

NDAs,  on  the  other  hand,  are  iwaitable  only  to  applications  that  use  the  desktop 
environment  supported  by  the  cs  tools.  This  is  because  an  NDA  is  ealled  up  by 
pullinfi  down  an  "Apple"  menu  in  the  menu  bar  (ereated  by  the  Menu  Managcr| 
and  selecting  the  NDA's  name.  Most  NDAs  treate  windows  that  may  coexist  on  the 

ill 


screen  with  windows  treated  by  the  application;  the  user  can  switch  between  desk 
accessory  wiridou'i  {iilsu  calli-d  vi/sftrDi  tihidow'i}  and  iipphcatinn  windows  in  the 
Uiual  way — by  tlitkiri);  in  the  window  to  be  aclivaled. 

The  purpose  of  this  chapter  w  to  show  how  to  write  pragrsmss  which  will  work 
pmperly  with  desk  'aLffSiDrics  and  how  to  write  desk  iiL'tessnry  programs  them- 
selves. This  involves  n  itudy  iif  a  tool  set  called  the  Desk  Manager  (tool  set  5), 

Before  specifics  are  diseussed.  a  prdiminary  word  about  the  Desk  Manager  is 
appropriate.  To  start  it  up  s«  thai  ymi  c-aij  desk  accesaories.  caJ]  the  DcskStartup 
tuiictiun.  Shut  it  down  vi.'ith  the  DeskShutDown  function.  Neither  function  requires 
panimeters  nor  generates  results. 

CLASSIC  DESK  ACCESSORIES 

An  applieatjon  does  not  have  tcj  do  much  to  support  classic  desk  atcessories.  It  just 
cannot  disable  interrupts  with  an  SEI  instruction  for  loii^  periods  of  time.  When 
interrupts  are  disabled,  the  cs  iRnOres  the  Cojitrol-Open Apple- Esc  kevl>c)ard  se- 
quenee,  sii  the  COA  menu  will  not  appear. 

Some  programs  may  need  to  disable  interrupts,  but  usually  only  for  brief  periods 
of  time.  If  you  art^  writing  such  a  pmKram,  be  sure  to  execute  a  CLl  (eleiSr  interrupt 
Sag)  instruetipn  once  it  is  sale  to  re-enable  interrupts. 

Writing  a  CDA 

A  CDA  is  iutually  a  ProDOS  16  load  file  that  begins  with  a  special  header  block 
containing  the  name  of  the  CDA.  the  addrcis  of  (he  subroutine  to  be  called  to  start 
it  up,  and  the  address  of  the  subroutine  to  be  called  when  DeskShutDown  is  ealUid. 
Here  is  the  a.s.'iembly-language  format  of  the  header; 

CDA_Header   STH      'CPA  Name"  ;NamE   {preceded  by  lengtti) 

DC       II  '  CDfl_E  tartup  '    ;Startiip  gubrouline 
DC       H  '  CDfl_5hu  IDwn  '    ;  ShiutDown  siibrout  i  ne 

The  start-up  .'iubroutinr  contains  tlie  main  code  for  the  CDA.  The  Desk  Manager 
calls  it  with  a  JSL  nistruction  in  full  native  mode  wb<"n  you  select  the  CDA  From 
the  CDA  menu,  The  subroutine  oiusl  end  with  an  RTL  instruction. 

The  Desk  Manager  eallsi  the  shul-down  subroutine  whene^x'r  the  DeskShutDown 
function  is  called.  An  applieation  normally  calls  this  function  just  l>efore  it  quits, 
but  it  is  also  called  when  thi-  dptraling  system  switches  between  ProDOS  IG  and 
PruDOS  S,  The  CDA's  shutdown  subroutine  can  terminate  any  background  task  the 
accessory  may  be  performini^  for  the  ciirreiil  application.  In  most  cases,  there  are 
no  Such  tasks,  so  the  shutdown  subroutine  is  just  a  shiple  RTL  instruction. 

A  CDA  can  use  any  of  the  te.xl  serecn  areas  in  banks  StX),  WI,  *E0,  5>E1  (offsets 
$400-$7FF)  without  fear  of  interfering  with  the  current  applieation,  Tliis  because 
the  Desk  Manager  saves  these  areas  Wftire  dispkyiug  the  CDA  menu  and  restores 
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thera  an  exit.  A  CDA  may  also  use  zero  page  [page  $00  of  bank  $00)  without 
bothering  to  presence  its  contents  as  Inng  as  it  respects  lliose  areas  uscri  by  the 
systeui  monitor  subroutines.  Any  other  mcinHry  the  CDA  needs  must  hr  alloi^ated 
with  the  Viemiiry  Manager. 

If  the  CDA  is  not  designed  ta  work  vtith  all  aperatinp  systems,  it  should  check 
locjatiun  StElOOBC  lo  see  whicli  one  is  active  and  then  lake  the  appropriate  action. 
The  niimbei-  stored  there  is  »00  for  PioDOS  8  or  $0i  for  ProDOS  16. 

Installing  a  CDA 

The  CDA  program  file  must  have  a  file  type  todc  of  SiB9,  and  you  must  place  it  in 
the  SYSTEM/DESK.ACCS/  siiljdi rectory  of  the  di;ik  from  wliit^h  you  hoot.  When 
you  boot  ProDOS  16,  the  system  aiitoniaticylly  installs  the  CDAs  il  find,';  in  this 
siibdiret'ton,-.  The  maxirtiuoi  nMinhcr  of  CDAs  that  may  be  installed  (including  the 
Ctmtrol  Pan*?!  and  Aliernate  Display  Mode  accessories  in  ROM)  is  foorteen. 

Lf  the  CDA  is  already  in  memor\'.  yiju  can  install  it  by  passing  its  handle  to 
InstallCUA,  Vou  probably  wdl  not  use  In.-itallCDA  ol'teu  because  it  is  more  conven- 
ient to  have  CDAs  installed  avitoinatiLally  at  haul  time. 

NEW  DESK  ACCESSORIES 

New  Desk  Accessories  are  more  diffit-iilt  for  an  application  to  support  because  ihey 
are  more  intimately  connected  to  an  application.  Whereas  a  CDA  takes  complete 
control  of  the  cs  until  you  exit  it,  an  NDA  shares  the  screen  with  the  application 
and  will  not  work  propfHy  vt-ithout  a  helping  hand  from  the  application. 

To  support  NDAs,  several  tool  sets  must  be  loaded  aod  started  up  before  you 
call  the  DcskStartup  Unction-  QuickDrnw,  Event  Manager,  Window  Manager, 
Menu  Manager,  Cootrol  Manager,  Scrap  Manager.  LineHIdil,  and  Dialog  Majiag;er. 
This  is  necessary  because  :ui  NDA  mu,st  he  permitted  to  call  functions  in  these  tool 
sets  without  having  to  load  RAM-based  tool  sets  or  having  to  execute  start-up 
fiinctions. 

The  easiest  way  lo  make  NDA*  available  to  an  application  is  to  use  a  TaskMaster 
event  loop,  because  TaskMa,stcr  makes  almost  all  necessary  liinction  calls  for  you. 
In  fact,  assuming  that  the  application  calls  DeskStarlup  at  the  beginniilg  and 
DeskShulDown  at  the  end,  it  need  only  use  FixApplcMenu  lu  add  the  names  of  all 
the  NDAs  to  a  standard  Apple  nienu^ 

PushWord  #1  ;1D  number  of   Apple  menu 

_F  i  «flp  p  1  eMerii 

The  NDA  items  are  assigned  consecutive  menu  item  ID  numbers,  beginning  with 
1.  (Retail  from  chapter  7  that  numbers  1  through  249  are  reserved  for  desk  accessory 

items. ) 
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If  you  are  not  using  T:iskMastrr.  NDA  support  is  more  complifated  and  involves 
calling  specific  Desk  Manager  functinns  at  appropriate  times.  The  following  para- 
graphs describe  huw  TaskMaiter  eimtrols  NDAf^  and  what  s.taiidard  actions  have  tn 
he  performed  if  a  GttNextEvent  event  Iwjp  wrrr  used. 

TaskMaster  knows  when  the  user  selects  a  desk  accessory  item  from  the  Apple 
mcnii  because  MeiiuSelect  returns  a  menu  ID  less  than  250.  When  this  occurs, 
TaskMa,stEr  calls  OpeiiNDA  to  open  the  de.sk  acctsj,.nry,  an  action  that  usuoUy  tuuses 
a  window  for  the  NDA  to  appear  on  the  wreen.  It  then  eiintFob  all  window 
lUanagemcnt  for  both  desk  accessory  and  application  window*;,  just  as  it  would  if 
multiple  application  vvintlows  were  on  the  screen. 

TaskMaster  handles  mouse-down  eveiilih  in  the  system  window  content  rc^iion  by 
callinR  SystemClick.  SysteinClick  passes  the  event  to  the  NDA  for  processing. 
Standard  editing  events  selected  from  the  Edit  menu  [Undo,  CJut,  Copy,  Paste,  and 
Clear  with  menu  IDs  from  250  to  2!>3)  are  liandled  by  calling  SystemEdil,  which 
passes  them  to  the  active  DA  for  processing. 

A  special  close  item  in  a  File  menu  [menu  ID  2561  is  handled  by  calliuR 
CloseNDAbyWioPtr.  This  paii^es  control  to  tb^e  close  subroutine  defined  in  the 
NDA. 

TaskMaster  also  allow*  NDAs  tt>  pfrform  any  periodic  activity  associated  mth 
them  by  calling  SystemTask  uiice  every  time  it  peiforms  its  internal  event  loop. 

Writing  an  NDA 

Like  a  CDA,  an  NDA  is  ii  ProDOS  16  load  file  that  he^ns  with  a  special  header 
blocic.  The  format  of  the  header  block  is  tjuite  diflereni:  than  that  for  a  CDA,  however. 
The  header-bhick  forinat  looks  like  this: 


Per  1 Dd 

EQU 

1#    of    t  J  C  k  5    belwe^^h   ruTi  aclinris 

Even  trio  3  k 

EQU 

IFFFF 

^in^^b  describing  events  wanted 

NDA^Header 

DC 

1  1  'NDfl^aper  ' 

iPcirter   to  open  SLibroutine 

DC 

l4'NDfi_Cl05E' 

;Pnirter    to  close  aubrouTine 

DC 

H'NDfl.Action' 

iPsinter    to  action  ^Libroutine 

DC 

l4'NDfi_lTiit' 

^Pointer    to    Ir^it  subroutinp 

DC 

12'PeriDd' 

DC 

DC 

■fiPlacelnotder    for  length 

DC 

C  '  J  leim  Name  ' 

;Te)(t  for   the  HDA  name 

DC 

C'\H"  '  .11  '0  ' 

^Cpace  of    [D  t    ;ero  byte 

As  you  can  see.  thie  hi^ader  heg^ins  with  pointers  to  four  standard  subroutines.  They 
will  be  described  below. 

Following  the  pointers  is  a  word  indicating  how  often  the  Desk  Manager  will 
pass  a  Run  code  to  the  NDA.Action  subroutine,  The  basic  unit  of  Period  is  a  timer 
tick  (I/60th  of  a  second),  so,  for  example,  a  Period  (tf  60  would  represent  one  second. 
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TherE'  iirc-  Kvd  special  Period  vaJut'S;  0  tells  thi?  Desk  Manager  to  pass  the  Run  code 
as  often  ^  possible  (in  practke.  this  means  niiLt^  evf  r>-  TtiskMasler  liKiph  ^FFFF 
tells  tlic  Desk  MuniiSt-r  not  to  pass  the  Kini  viAl-  al  all. 

The  event  mu^k  iiiJicat('_s  wliich  events  will  causr  the  Desk  Mkiiagcr  to  pass  an 
Event  ctide  to  the  NDA.Aclimi  siibrnutinc  The  iiiPiining  uf  ihe  musk  is  the  same 
as  that  for  the  event  mask  described  in  chiipter  5  in  coimectiun  with  llie  C;el- 
NcxtEvt-nl  and  TnskMaster  finietinns.  In  most  e^i^es  vun  vA\\  set  it  ti>  SFFFF  (all 
evt'nts). 

The  fin:d  lli  m  in  the  ht-ader  is  the  name  of  the  NDA.  in  the  iorinat  expected  by 
the  Menu  Manager  U  bej;iiis  vvith  two  placeholders  for  the  lenRth  and  is  followed 
by  the  tejtt  of  the  ]iaiTie  and  then  a  M  t*'*  vinuu\.mi\  iihii  reserves  space  for  the  menu 
IDl.  A  trailing  U  byte  murks  the  end  of  the  item  definition. 

The  nojit  seetion  takes  .i  dnsf  lex.!;  .u  eiieh  of  the  fnur  subroutines  an  NDA  mu-it 
eciiildii  Ynu  may  want  to  refer  to  li^tni.e  9-1.  wbifli  shows  how  to  implement  a 
einek  desk  aecessnr>',  for  practieal  implenictitatiuEi  insfmetions. 

NDA  Open.  The  NDA_0|ien  snbi-ouliin;  must  prei^are  the  desk  accessiirj  for  use, 
but  nnlv  if  it  is  nut  already  open.  In  iTio.st  eases  this  involves  ereatitig  a  ^vindow  for 
the  NDA  usinK  the  NewrWiiidow  funetiun,  iiwmg  the  window  pointer  ior  later  use, 
and  markitsEl  the  window  as  a  system  window  using  the  St^tSys Window  function. 

Befbre  thf  Ufsk  Manaijer  makes  a  eall  to  \DA_Opeii  witli  a  JSL  inftlrneti^jn,  it 
ieser\es  space  on  the  .staek  foi  a  lony  word  result.  NDA_Open  must  return  tlie 
NDA's  window  pointer  here  before  exiting  with  an  HTL  instruction. 

On  entr>  to  the  NDA_Open  subroutine  (or  the  other  three  standard  subroutines), 
the  fi.5S16  will  be  in  bill  native  mode,  At  thi.'  start  of  the  subroutine.  y<ni  should 
execute  PHB,  PHK.  and  PLB  instructions  to  make  the  diita  bank  register  equal  to 
the  code  bank  rei^isttr.  This  lets  you  access  memory  locations  within  the  desk 
accessor'  eode  spacif  w  ith  absolute  addressmy  rather  than  ab^hite  long  addressing. 
On  exit.'  be  sure  to  execute  a  PLB  instruction  to  restore  the  data  bank  register  to 
its  ori^iina]  slate. 

NDA_Close.  The  NDA.aose  subroutine  i.s  responsible  for  shutting  down  the 
aeeeasory.  usually  bv  closing  its  «'indow  with  the  CloseWindow  hmcliom.  It  doe.s 
not  return  a  result.  This  subrontine  is  automatically  called  by  TaskMaster  if  you 
Lhek  the  ekjse  box  oo  llse  VDA  windi)w  or  if  you  select  the  special  Close  item  from 
a  menn  (it  has  a  memi  ID  nf  255). 

S'DAJnit.  This  iiiitiulizaiion  snbrouline  is  called  whenever  the  application  calls 
the  DeskStartnp  or  f>eskShntDown  funetiun.  On  entry,  the  accumulator  is  0  it  a 
call  to  DeskShutDoun  was  made;  U  is  non-zero  for  L-alls  tn  DeskStartup. 

Most  imtiahziition  subroutines  do  not  have  tn  do  arjyfbios  when  DeskStailup  is 
called,  because  the  NDA  is  not  ^ven  intefirated  with  the  application  al  this  stage. 
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Table  9—1:    AcHon  Codes  for  New  Dcsik  Att  t^ssdrirH 


Action  Cade  Ta^k 


1  Event 

A  jTinuse-down.  iJiouse-ii[x  Jiey-dow'n,  autokey-dowii,  update,  iir 
aclivute  event  took  place,  sii  process  it,  A  pniiiler  to  ihe  event 
r^'t'(>rtl  is  in  X  (low)  and  V  (hi^h), 

a  Run 

The  Pcrintl  has  elapsed,  in  pt'rforim  the  perindic  action. 

3  Cursor 

Tlie  NL>A  windcnv  is  activf.  so  chanjif  thi"  trursnr  if  nrrccssarj'. 

4  [Reseri'ed] 

3  Undo 

The  special  Undo  item  (ID  250)  was  seleijteJ,  su  prneejis  it. 

6  Cut 

The  speuial  Cut  Item  (ID  251)  was  selected,  so  pruceiss  it. 

7  Copy 

The  special  Copj'  item  (ID  252}  was  selected,  so  process  it, 

8  Paste 

The  special  Paste  item  (ID  253)  was  selected,  so  process  it. 

9  Clear 

The  special  Clear  item  (ID  254)  was  selected,      process  it, 


When  DeskShutDown  is  rallcfl,  the  window  should  lie  closed  to  release  the 

menion'  it  occupies  or  to  terminate  sninc  activity  tied  lo  the  application. 


SDA^Action.  The  moat  ditBcuIt  isuhrciutine  to  pnijirdm  i.s  the  action  snhniutine. 
It  is  respniisiblf  for  liaiidliii^  an>  uriiinc  tiLsks  timt  ni^iy  he  pLLs^bcd  to  il  For  processing. 
The  action  code  lor  the  task  is  ptlS^ed  in  the  aL-cumulator  iind  can  be  caic  ui  iht; 
values  shown  iii  lahle  9-1, 

For  action  t'otlcs  5  tn  9  [llie  etiiliiis);  coinTiiands!,  a  niin-zero  vaUif  r*'tumcd  in 
the  atcuitiulator  it"  tlie  action  was  handled  (the  usual  easel  or  0  if  it  wa-s  not. 

The  Riui  la,sk  slioiilt!  he  protessctl  by  [M-rtonuiiiji  the  periodic  Miction  asNiiciatetJ 
with  the  NDA-  Tlie  clock  iKxessory  in  listiufi  y-1 ,  nliich  liaii  a  I'eriod  of  one  aec-ond, 
prnccjiscs  the  Run  code  by  displaying  the  current  tijne.  In  olher  types  ol  accessories, 
you  may  want  to  hiink  a  cursor,  update  a  system  status  display,  or  perform  other 
similar  tasks. 
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Tlie  Cursor  task  is  called  imce  every  TaskMastci  loop,  but  only  if  the  NDA 
window  is  open.  It  all^ms  the  accessory  tn  chan^t-  the  HL-Vive  cursor  depending  on 
the  current  position  oJ  the  inuuse.  For  47^amplt%  yoii  uiighl  want  to  change  the 
cursor  to  u  bulls-irvf  if  the  oiQUSC  happens  tn  ht'  inside  the  tonlent  region  uf  the 
desk  act'cji'ior)-  winiiow'.  The  example  acccsson'  shows  how  to  detcrminr  if  the  mouse 
is  inside  a.n  NDA  \viiitlo\v',  how  tn  change  the  eursor  to  a  wristwateh  if  it  is,  and 
how  to  restore  the  original  cursor  if  it  is  mit. 

The  Event  task  handles  the  .six  .stantlord  CS  events  mcnKnned  ahove.  Ttie  trickiest 
handler  is  probablv  the  one  for  update  events,  it  must  call  Bej;in  Update  (to  make 
the  visible  region  the  same  as  the  update  region  temporarily),  redraw  the  contents 
of  tlie  wbidow,  and  then  call  Endlipd;ite  [to  restore  the  original  visible  region  and 
empty  the  iipdalt-  region).  The  clock  N  DA  redraws  the  window  simply  by  displaying 
the  current  time, 

Tlie  handler  for  activate  evejits  must  fir^t  distinsjuish  bettt'een  an  activate  and  a 
deactivate  optTati^m.  It  can  do  tills  hy  exa.mininK  hit  U  of  the  inodiRcrs  wiird  d"  the 
event  record:  if  it  is  0.  the  NDA  window  is  beins  deactivated.  In  the  example,  a 
deactivate  event  is  handled  by  restoring  the  original  cursor. 

Notice  the  techniijue  used  iii  the  example  for  aet;es^iog  the  modifiers  field  in  the 
event  record.  On  entry  to  the  NDA_Action  subroutine,  a  pointer  to  the  event  record 
(stored  in  X  and  Y)  is  pushed  on  the  stack,  Liter,  a  direct  page  that  in  aligned  with 
the  stack  pointer  is  created  sa  that  the  fields  in  the  event  rccfird,  a  pointer  to  which 
is  now  in  direct  page,  c>an  be  accessed  with  the  [dp].Y  addressing  mode. 


Installinji  an  NDA 

NDAs  aR=  PrciDOS  16  load  files  that  have  a  file  type  cotle  ofSBH  Only  those  NDA 
files  that  are  located  to  the  SYSTEM/DESK, ACCS/  subdirtTtory  on  the  boot  disk 
■i\  boot  time  wdl  be  added  to  the  Apple  menu  when  you  call  the  F*ixAppleMc'nu 
function. 
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Table  R9^l!     The  Major  Functions  in  the  Desk  Manager  Tool  Set  (805) 


Function  Name 

CloseNDA 

CloseNDAbvWinPtr 


Function 
Niimher 


$1C 


Desk  Startup  $02 
DeskShulDowii  S03 


Stuck 

Parameters 


RefNum  (W) 
TheVVindow  (L) 

[no  parameters] 
[no  paranieter:s] 


Descripiwn  of 
Ptirameter 


NDA  reference  number 

Pomter  to  CDA 
window 
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Function  Name 
FixAppIeMenu 

InstallCDA 
Open  N  DA 


SystemClick 


SyK  tern  Edit 


i'unclioii 


$0F 
$15 


$17 


$18 


Stuck 

Para/mlers 


Dctrription  of 
Parameter 


MeiiulD  (W) 

ID  Handle  (L) 
result  (W) 

DAIDNumhcT  (\V1 

EventRecord  (L) 
TheWiiidow  (L) 

FindWiiidRea  <W) 

result  (W) 

EditType  (W) 


ID  of  iHEnu  to  add  DAs 
to 

Handle  In  CDA  header 

Reference  number  for 
NDA 

Menu  item  ID  number 
for  NDA 

Ptr  to  event  record 

Ptr  tn  NDA  window 
rpL-ord 

Result  of  FindWindow 
call 

Boolean:  did  NDA 
handle  edit? 

Code  for  edit 

command: 

1  =  undo,  2  —  cut, 
3  =  copy,  4  =  paste, 
5  -  clear 


SvsteniTask 


$19 


Ino  parameters] 


Table  K9-2:     Desk  Manager  Error  Codes 


Error 
Code 


$0510 
$0511 


De-vcriptian  of  Error  Conditioti 


The  specified  desk  acees.snry  was  aol  found. 

Hie  window  is  nut  an  NDA  [system) 
window. 
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Listing  9-h     A  New  Desk  AeL-essow 


This    program    ahaiiws    haw    tc    con^trijct    B  ■ 

»  Hew  Desk   ficces'sory   (NDfl).   The  HDfi  • 

»  de-fined  here   is  m   clock   windouF  which  ■ 

*  coTilaiTis  the  curreTit  time  and  dole;  Ihe  * 
■   I  Ims  and  d^le  arf:  updated  arcs  per  • 

•  second.  ' 


LJ5T  OFF 

SYMBOL  OFF 

ABSADDf?  DN 

INSTIME  ON 


GEN 


□  N 


KEEP 


CLOCK 


;  Code  1 1 


nCQPY 


CLOCK .MAC 


;t1flc  ro  file 


Per lod 


GEQU 


IFFFF 


;Aafc  for  "run"  action  every  second 
;Handlc  all  euents 


DC  l4'MDft_apen' 

DC  I4'hDS_C]oae" 

DC  I4'NDfl_flctitini 

DC  H'HDft^rnit' 

DC  I2'Period' 

DC  12'Eveninaiik  ' 

DC  C • '  ' 

DC  C'Clacki 

DC  C • \ H • • '  ,  J 1  ^  0  • 


□pen  the  HDA 

Close  the  NDfl 

Perform  NDfl  ac I  ion 

StartupyShatdown  the  NDft 

Periodicity  of    "ruTi"  acticn 

Permitted  evfcnts 

Name   in  menu,    item  form 

TeiE    far    NDft  neifne 

ID  field  •  terminator 


Open  the  HDfl  if   it  has  nol  been  previoualiy  opened.  This  routine 
must  return  a  pointer  to  the  NDfl  window  on  the  stacic,   juat  above 
the  3-b/te  return  address.    The  De5fc   nanager   reserves   this  result 
space  just   before  calling  HDft^Qpen  with  p  JSL    i n^ I r uc 1 i on . 


NDfl.Open  flNOf 
Result  EQU 


SOS 


;R=5ult    5tack    offset  after   JSL,  PHB 


PHB 
PtB 


idata  bank   =  code  bank 


LDA 
BNE 


Cloc  kDpen 
Ignore 


;Clocl:  Window  already  open' 
;  1  f   50  ,  branch 
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PHA 
PHfl 

PushPtr  bJindowDef 
_Newl>li  rdow 

PLX 
PLA 


STX 


Hi  TidowPlr 
LiJnidowPtr  +  3 

ResLi]  l'^2.S 


I g  nor  e 


STf^ 

STfl  Result, S 

PuihLong  Ui r^dowPlr 
_5e  t  SysW 1 rdou 

LDfl  #*FFFF 
STA  ClocbDpffn 

PHfl 
PHA 

_Qe  t  Cur  sorfldr 
PopLong  DldCursor 

PLB 
STL 


i 5pac e  for  result 


lCr«al»  and  open  NDA  window 

jPop  pointer  [low] 
;Pop  poiTi1.Er  [high) 


iSavE  reaull    or  stack  (high) 
;  (low) 

jDark   this  35  a  Dfl  window 

;Stt  "open"  flag 
;9pdce  for  result 

;  Save  pointer  to  regular  cursor 


;  Close  the  MD^  if  It  l9  not  already  closed: 
NDA.Cloae  f\WP 


PHB 

PHK 
PLB 


C loc  taper 
Ignore 


PushLuTig  W  mdowP  t  r 
C  1 D9  eUi  ndouj 


5TZ 


C  loctDpen 


PushLong  DldCursnr 
.SelCur aor 

PLB 


idata  bank   =   code  ban* 

;Ia  the  clock  windoM  open? 

;Mo,    sa  branch 


;Gel    rid  of    the  window 
;f1ark   clack  59  closed 

iRealore  applicalion  curaor 
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■;  Perform 

the  NDA 

act  L^ri  : 

SNDP 

r  no 

PHK 

PLB 

a  u  V 

rm 

r  n* 

ft  cl 

R 

InA 

[  Hc  I  i  on  1  Di  ,  it ) 

rL  Jl 

PLY 

PLB 

RTL 

BctiorTbl 

ANDP 

DC 

t2'NoflctiDr' 

DC 

I2'NDfl_Everl' 

DC 

E  2 ' NDfl_Run  ' 

DC 

t  d  '  riVR_L  u  r  s  or 

DC 

l'5lhJT>i               ,w-  -4  I 

DC 

1 1^  '  Mi3iR._L-u  t  ■ 

DC 

1 2 ' NDA_Copy ' 

DC 

DC 

12'NDA_Clear' 

HoAc  I  iovt 

AWOP 

RTS 

HDA^Rsrvd 

ANOP 

RTS 

NDA_Ufido 

ANDP 

NDA_Cul 

ANQP 

NDA_Copy 

ANQP 

ANQP 

A  HOP 

1  Save  da  la  bank 

;I1ake  dala  bant    ^  program  hanI: 

iSave   incDmng  parametera 
ifevemt    record  or  menu  infoj 

;xE  to  alep  inlo  lable 
iFix  up  the  stack 


□  n  eKit   fl  =  0    if   edit   comma nd  w-asn'l   handled;    non-rero   if    il  wa*. 

You  will  uQLJBlly  Mjant   to  say  it  was  handled,   because  the  applicatior 

will   not   be  active  371^         stiDuJcln't   bc  dcs'irg  with  edit    commands  . 


LDA 
RTS 


'»FFFF 


\^ay  Mc  handled  il 
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J  Display  a  wrist^steh  curaor   if   the  cursor  is  over  top  of 

;   the  contert   region  cf  the  windoM.  This  routine  15  only  called 

;    when    the    Df\    wi  ndow    15    the    front  uindnw. 


HDA.Curscr  ANDP 

PHfl 
PHfl 

.GetPort 

PushLoTig  MindoLi/Ptr 
_SetPort 

PuahPtr  PortRect 
_GelPor  tRect 

PuahPtr  MouaePoaTi 

_Oeirioii3e 

PHfi 

PuahPtr  Mou5ePci9Ti 
PushPtr  PortRect 
_Pt InRect 

PLfl 

BEQ  NDA_Cur5l 

;  Ewitch   to  ufiatch  cursor,   but  only 

PHfl 
PHfl 

_&E  tCursDrfldr 

PL^^ 

PLX 

CMP  'WatchCurs 

BNE  NDA.CuraO 

CPX  tf 'WatchCura 

BLO  NDA^Cur«3 

NDfl.Cursa     PuahPtr  WatchCurs 
BPfA  MDA_Cur^2 

5    Switch    to    application    cursor,  but 

NDfl.Cural  PHA 

PHA 

_{je  tCur^orfidr 

PLA 

PLX 


;SBve    current  GrafPijrt 

iMoke  clock  window  active  GrafPort 

;&et    Ihiff  port    rectangle    (local  coord 

iRelurn  pDsition    in  GrafPort  coorda 

;Get  cursor  position 

;apflce   for  result 

spoinler   to  mouse  coordinate 

Ipointer  to  content   rcgjon  rectangle 

;l5  point    in  content  region? 

[No,    'ha  hj'anch 

f    it's  not  ■already  active: 

;Get   current    cursor  pointer 

;  I  5   it  the  luatch? 
;  Def  ini  te ly  not 
;  Is   it  the  watch' 
iYes,    50  dp  nothing 

only    if    it's    not  already  active: 
j6et   current  cuLrHDr  pointer 
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CMP 

CPX 
BNE 


•WatchCurs 
IH0A_Cur53 
*''Walc:hCiirB 
NDft..Cura3 


NDA_Cjr5  5  t  Cur  5  or 


1  Ts   it   the  watch? 

;Nq,   50  don*l  do  anything 

;  Is  it  the  watch'' 

;Mo,   5D  don't  do  anything 

jSwitch  to  application  cursor 


iReatore  GrafPort 


;  Thjg  Hubrautire  is  called  once  e^'cry  "Period"  ticks- 
NDfl.RuTi  flNOP 


PHfl 
PHfl 

_GelPart 

PushLong  WindowPtr 
SetPar  t 


;Spacff  for  result 
j'Save   current  port 


iSwjtch  to  cloct  window  for  drawing 
;Pi5piay  the  new  time 
;(Painter   5ti.ll   on  stacli) 


JSR  ShowTime 
.SetPart 

RT5 

}  X  and  Y  (pushed  on  stacl:)   contaiT^  pointer  to  event  record 


TheEven  t 


T£1 


AHDP 

EQU 

105 

PHD 

TSC 

TCD 

LDA 

[TheEwent] 

CMP 

BC5 

TE1 

ASL 

TAX 

J5R 

(EventTbl ,K) 

PLD 

RTS 

|1    (base)   *  £   [JSRJ   *  2  [PHD) 


;Atlgn  d-p-   with  stack 

;Get  "what"  code 
{Anything  we  support? 
;No,    50  branch 

■,x2  to  5tep   into  table 


; Restore  direct  page 
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I2'Dot1oLiaeDwfi' 
[2*DaMou9GUp< 

E2'DQfiutoKeyf 
I2'DoUpdflte' 


EventTbl  ANDP 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 

DoMouseUp  f^HUP 
DonouscDwrv  flhDP 

NoEwETit  RTS 

DdUpdate  AMQP 

PushLong  WindowPtr 
^Beg  L  nUpda  te 


ShowTim* 


PushLoTig  Ui  ndowP  t  r 


Not  supported 

rioLise  -  d  own 

Mou'se  -  up 

fCpy  dawn 
Not  -supported 

autgkey 

Update 
Not  supported 

Act  1  vat e 


;\'i.9lbl«  region  ■  update  region 
(Diaplay  the  current  time 

{Restore  Entire  wistble  region^ 


RTS 


;  If  NDA  filndow  ia  deactivated,  return  to  origiriat  cursor. 
DoActivate  ANDP 


HDA.Dff 


ShowTi  me 


LDV 
LDA 
AND 

se:q 

RTS 


i-l  4 

[TheEvETit]  ,Y 


PushLong  nidCuraor 

_5etCuraor 

RTS 

PuahPtr  ThcTimc 
GtfldAsc 1 1  Time 


LDNCA 


'(2D 

□  FF 


;ncce9ai  modifiers  field 

jfaoldte  actii/ate/deactLvste  flBQ 
; [f  0  ,  deact ivste 


l5uitch  to  previous  cura-or 


i Read  the  clock 
[B-bit  A  register  for  byte  ecceSSeH 
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LDY 

ftND 

ETft 
DEY 
BPL 

KEP 


»19 

TheTime , V 
»)7F 

ThcTime.r 
STl 

•  120 

OH 


PuahWord  ^20 
PuahWord 

_MoweTa 

PuahPtr  ThcTime 
_DrawCSt  r i ng 

RTS 


iConvert    ta  standard 


iBack   to  16-bit  fl  register 


ihor I zorlal 
■,  ver  t  Aca  1 


vDraw  the  time  string 


;   Startup  ar   shut down   the  NDfl .    Un  entry,  for  De s  k  Shu  t Dawn , 

i   ft   IS   non-zero   for  DeakSlarlup. 

Nnfl    lnjt  ANDP 


PHB 
PHK 
PLB 

cnp 

LDA 


•  0 

NDfl^lnitl 

C 1  Qcb  U^en 
NDfl  Initl 


PuahLorg  UindowPtr 


STZ 

HEA_lnit1  PLB 
RTL 


Clock  Open 


iSlar  1 1  ng  up'' 

V  Vc5  ,   SD  do  not  h i ng 

^Clock  windfiw  open? 
;Nd>   sg  branch 


^Cloap  the  windQUi  [releases  memory) 
;Spt    "closed"  flag 


I  The  data  area  begins  here: 
HEA_Title     SIR  ^ Ca 1 e nda r / C I ocfc  ' 


;  1^1  ndow  title 


UlndcwDef  AIHOP 

D:  1  2  'EridWind-WiTidowD*f  ' 

DC  1 01 00000 •    sWindo-  with  close  box,  title 

DC  I  4  '  HDA_T  1 1  le  '  iPomler   to  window  name 
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Endkllrd 


DC 

M 

D' 

ft  ^ 

DC 

\2 

D  , 

DC 

l-l 

DC 

14 

0' 

DC 

14 

C 

DC 

14 

0> 

DC 

H 

0' 

DC 

14 

0' 

DC 

H 

0' 

nc 

12 

D' 

DC 

lA 

DC 

14 

0' 

DC 

H 

0  ' 

DC 

PED  , 

DC 

H 

-1 

DC 

14  1  □  ' 

AHQP 

jDrigjn  at  [C,0) 


;  (Handle  oiir  awn  updates) 
■,D  1  mensl  OTia  of  wirdaw 
;Put   clack  wmd'ow   in  fj-ont 


W 1 n  dowP  t  r 
CI  DC  t  Dper 

PortRecl 
iHou  SePaan 

TheT Ime 


;  This  1^ 
UlalchCurs 


DS 

DS 

DS 
DS 

DS 
DC 

DC 

DS 


4 
2 

B 
4 

C 

I  1  ■  0  ' 


the  curs&r   record  for  a 


DC 

DC 

DC 
DC 
DC 

DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 

DC 

DC 
DC 


12' 12" 

I2'3' 

H I OQOOOODDOOaO ' 
H' OaOFFOODDGOO  ' 
H' OaOFFOOOQOOD  ' 

H <  oarooFooDcoo  > 

H' OFOOFOFODQOD  ' 
H'OfOaFOFO-OODO  ' 
H' OFOFFOFrOOOD  • 
H'OFOaODFOOOQDi 
H  '  OOFDOFOOOO-DD  ^ 
H'OODFFaQQOOOO- 
JJ'OOOFFOOOOOOO' 
H  '  QODDOOQCIDDOO  ■ 


H  '  aOOFFOOOOOOC I 
H«  OOFFFFOaGaOO ' 
HI aOFFFFOOOOOQ  ' 


iPointer   to  window  record 
iUsed  as  h  fia^ 

;Content  region  rectangle 
^Current  mouae  position  (local) 

;  Readft  5c  I  iT  Lme  returrva   ?0  byte5 
;Add  paddifiQ 

^{terminator   for  DrawCSt r j ng j 

;Poinler   to  appi  4     1 4  on  '  s  curaor  recur 

"wristwatch"  curaor: 

IRdwB    in    cursor  image 
;Cijr5or  width   (in  words) 

;The  Cursor  im^g? 


;The  cLirsgr  ma  si; 
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DC  W'OFFFFFFOOOOOi 

DC  H  '  FFFFFFFFOOOO ' 

DC  HTFFFFFFFOOOO' 

DC  H ' FFFFFfFFFOOO ' 

DC  H'FFFFFFFFODOO' 

DC  H' DfFFFFFODOOO  ' 

DC  H' QOFFFFDOOOOO  ■ 

DC  H' OaFFFFaDDOOO  ' 

DC  H'OOOrFDOCODQa' 

PC  12'e,B' 

END 


;Hcjl  spot  (y,3c) 
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CHAPTER  10 


The  ProDOS  16 

Operating 

System 


The  software  interface  between  an  application  program  and  a  mass-storage  de-vite 
sych  as  a  disk  drive  is  eallctl  a  tlisk  npi-rcitiiiil  Mfsti'in.  Its  main  respunsiliilities  Arv 
tn  organise  data  and  proyrMin  files  mi  the  disk  medium  and  tu  provide  simple 
mnclianism  applicati(Mifi  can  use  to  transfer  data  tti  and  from  tliese  files.  Oilier 
common  chore's  a  disk  operalirij;  system  performs  are  file  ereation,  deletion,  and 
renaming,  and  vtilume  in anaHt^ intent. 

For  the  past  ft-w  years,  the  Standard  operating  system  for  the  Apple  II  family  has 
he-L-n  ProDOS,  the  Prciressimiiil  Disk  Operating  System,  The  origiiial  release  of 
PriiDOS,  since  renamed  ProDOS  S,  was  designed  spefifically  for  the  lie,  lie,  and 
11  Plus,  and  w(3rl(s  in  the  6.5C02's  (ur  6302'sl  &4K  memory  space  only. 

Frt)UOS  b  alau  works  with  a  CS  that  is  running  Ilc-slyle  applicatinns,  of  course, 
bjt  it  will  not  work  with  CS-specilic  applitations,  bet.'aii.se  they  arc  not  t^nnfincd  tn 
the  first  64K  of  ineinorv-  To  solve  this  problem.  Apple  Computer.  Inc.  created 
ProDOS  16,  aTi  operaiinp  system  that  is  similar  in  structure  to  ProDOS  S  hut  that 
takes  advantaf^e  uf  the  entire  GS  memory'  space, 

FroDOS  16  runs  in  65816  native  mode,  which  means  it  works  nn  the  Apple  Una 
only.  If  you  try  to  boot  i*  on  another  type  of  Apple  II  you  will  sec  an  appropriate 
error  mesijage.  Programs  that  work  wi(b  ProDOS  8  will  not  work  with  PniDOS  16, 
because  ProDOS  16  nses  a  new  cominand  calling  sequence.  Fortunately,  program- 
niers  sbonld  find  it  rt'latively  easy  to  adapt  prn.u;ram'i  to  ProDOS  16,  bt'caiise  most 
ProDO,S  S  cninmaiids  have  ProDOS  16  equivalents^  with  the  same  symbolic  names 
and  similar  types  of  command  parameters. 

Both  versinns  of  ProDOS  format  disks  and  store  files  in  e.'iflCtly  the  sanne  way. 
Tlius,  data  Rles  can  tic  aeccs^cd  directly  by  either  Operating  system.  ProDOS  16  is 
even  capable  of  switching  to  ProDOS  8  if  the  proper  system  files  are  included  on 
the  start-up  disk. 
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This  fhapfcr  Irwiks  At  thr  matri  fcahiR'S  of  FrnDOfi  Ifi  and  ^ives  sf  vcial  examplns 
of  huw  to  use  PniDOS  16  LtJiiunaiids  Iroiii  witliiri  u  projii  iini,  U  also  reviews  some 
fif  t^e  jargiin  associated  with  FmDOS  in  general  and  PniOOS  16  in  particidar. 
ProDOS  H  has  been  covcre-d  in  great  deUiil  in  Aj^^jir  FniDOS:  Advmucd  Fecitun'S 
for  Programmers  (LitHc  1985).  That  subject  matter  will  imt  he  repeated  here- 

BLOCK  STRUCTURED  DEMCES 

ProD<3S  16  works  with  hhck-:^tritctuicil  shirage  devices  only.  A  hinck  is  a  ^roup  of 
512"hytf'^  d  data  and  reprfspiUs  tlie  stnalk-st  unit  ol  inforEnatifin  the  device  tuntroller 
can  Tcud  or  write.  Contras^t  thi;;  with  character  devic-es,  such  as  printers  or  modems 
whif-'h  deal  wilrh  imly  one  tharaLler  at  a  time. 

The  most  tiimmuii  blnck-strutlurt-d  devices  used  with  PruDOS  k(i  on  the  cs  are 
the-  fnllowing  disk  drives: 

-  3  Va-ineh  disk  drives  (Apple  3,5  Drive,  UniUisk  .l.S) 

-  S  i/4-ineh  disk  drives  {Apple  5.25  Drive,  DniDisk  5,2S,  DuoDiak.  Disk  H) 

-  Hard  disks  (Hard  Disk  20SC,  FroFiU-^ 

Apprndix  7  descrihes  how  to  t-oniiect  1  Vi-inth  und  5  "/4-tnch  drives  to  the  c;S. 

]n  addjtion.  if  is  possible  to  piirtilion  and  fon%iire  an  area  of  ineniory  So  that 
ProDOS  16  thinks  it  is  a  btnik -structured  device  ealled  a  RAM  disk.  The  advantage 
of  usin^i  a  BA^^  disk  instead  t>fa  niechajiieal  disk  drix  e  is  that  input/output  operations 
are  niudi  quicker  You  must  remcndier  lo  save  files  on  the  RAM  disk  to  a  real  disk 
before  yoii  turn  off  the  c;a,  Kowevrr. 

The  eaj^iest  way  to  create  a  HAM  disk  is  to  use  the  Control  Pamd  de^k  accessory. 
With  it  vou  can  allocate  all  or  a  piirtion  of  the  menmn,'  on  a  cs  memory  espsmsion 
card  for  RAM  disk  use.  If  you  formal  this  R.\M  disk  and  put  the  oecessary  operating 
system  Files  on  it,  you  caii  even  boot  from  it  when  you  press  Con  trol -Op  Fn  Apple - 
Reset.  To  select  it  as  the  hoot  deviM-.  u_^e  tlie  Control  Tancl  Slots  connnand  to 
chanpe  the  Boot  0]Hioil, 

DIRECTORIES  AND  FILES 

A  nolunie  is  the  seneral  name  for  (he  storage  mcditim  used  by  a  block-structured 
device.  Each  volume  formatted  by  ProDOS  16  contains  one  or  more  ilireciories  in 
which  files  may  be  stored.  The  mam  director.-,  called  the  Duiunw  dirtciory  or  the 
root  (hrcctury.  is  c  reated  when  you  format  the  disk;  it  may  t-ontain  up  to  51  entries, 
representing  ordinary^  data  files  or  mbd'mxUiry  Hies.  A  subdirectory  may  contain  as 
many  entries  as  ^pate  permits,  including:  other  suImIi rectories..  See  figure  10-1  for 
a  diagram  showing  bow  iniilti|ile  directnries  on  a  volume  are  iitterrelaled. 

The  ability  to  create  a  hierarchy  of  directories  nukes  it  easy  lo  nianane  lar^e 
numbers  of  iiles  on  a  '^int^le  disk,  This  is  l>ecause  jjroups  of  related  files  eaii  be 
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Figure  10-1.     The  ProDOS  Hicrjirfhicjl  Dirc-ciuri'  Structune 


Volume  Oircctorff 


/WORK/ 

PRODOS 

svs 

BASIC.SVSTEM 

svs 

STARTUP 

DAS 

LETTERS 

DIR 

PROGRAMS 

DIR 

/  VQRK /LETTER S/ 

^  LETTERS/ 


TO.EDITQR  m 
GSeOOK  DIR 


/V  ORK  /  P  RO  G  R  AhlS  / 


PROGRAMS/ 


ANIMALS  BAS 
FTP  CODE  SVS 
PTP.ie  S16 


/V0RK/LETTERS/GS.DOOK/ 


GS.BOOK/ 


CHAPTER.  1  TXT 
CHAPTER. 2  TXT 


isolated  in  their  own  separate  directories  where  they  wiJI  not  be  mixed  with  the 
many  otiu-f  liirs  rm  tiir  disk. 

Evcr>'  fil<'  fin  ;i  disk  is  assciciated  with  a  fUenrntu:  up  to  fifteen  characters  long. 
The  fir-st  tlwiiL-ter  niusl  be  s  letter  iif  the  alphabet  Iroin  A  to  Z,  Imt  subsetjuent 
charaettTs  can  br  l»?ttffr^.  diflits  (0  tu  91,  ur  periods, 

Bctaiisf  of  Iht"  way  direfturit-s;  okn  be  nestt-d  when  iiiin;;;  ProDOS  Ifi,  it  is  not 
entiii|ili  tn  identify  a  file  liy  its  nanie  Only.  You  must  also  identify  the  directory  in 
whit'h  the  file  is  stijrecl.  The  itlentifyiuR  string  required  by  ProDOS  IG  is  called  a 
\mlhn<sme.  It  is  a  {.'(incatenatiun  oi'  tlie  niiine.s  of  each  of  the  directories  ProDOS  16 
must  pass  thruu^h  tu  reath  ihe  file  s  subdireetniry,  fnllnwed  by  the  name  iif  the  file 
ilseli.  The  pathname  begins  with  a  slash  (/)  and  esch  direetnry  nanu'  in  tke  pathname 
\i  separated  fruni  the  next  with  si  slash- 
Suppose  the  name  uf  llie  vulunie  directory  of  yniir  disk  \s  VVOfiK  and  within  this 
direelorv  yon  have  defined  a  sulKlireclory  caHed  IjETTERS  that  ftintains  a  file  calked 
TO. EDITOR.  Th*;  p;ilhii^uie7  to  nsfr  to  identify  this  RIe  is: 


^WORK/LETTERS ^TQ. ED] TOR 
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Yhu  can  avoiti  iptsjiKing  a  complete  pathname  every  time  you  want  to  deal  with  a 
file-  hy  'ictliiig  a  ikfatdt  prefix.  A  (!ef;nilt  prcfiv  idcntififs  thf  path  to  a  piirtiLuliir 
ilirL'ct(>r\'.  and  PnjDOS  16  aiitniiiafiLiilly  puts  !hj,t  ji;iUi  in  front  <]f  any  fileniiiiie  you 
specify.  It  will  iiku  put  it  in  fronl  of  a  partial  jiathname.  A  partja]  pathname  is  a 
name  dpscrribiiiR  ^  scrie-i  ■irtJirettories  that  dutrs  not  hfgiii  with  a  sksh  Essentially, 
a  partial  ijathiiaiiif  is  the  [>iir)mamt  of  li  Bk-  icIadM'  to  [Ue  dirtsctnry  described  by 
the  defmdl  prefix. 

For  L-xaniple.  if  ynu  ?iet  tht-  (IHkiilt  |^^L'Ei^  tn  AVOBK^LLTTERS  in  the  above 
example,  yuu  [■oidd  identify  TO.EDITOH  hv  it^  filenani!'  only-  11  the  delkult  prefix 
was  /WORK/,  you  would  ^jM-dfy  the  partial  (lalhiiaint'  LETTEK^i/lO.  EDITOR. 

'I'he  default  prefix  Lan  also  he  represented  by  the  name  tJ/.  Tims,  O/TO.EPITOR 
is  equivalent  \x>  /W'OIIK/LETTEHS/TO.EDITOH  if  the  0/  preh>L  has  hec^i  ^et  to 
/WORK/ LETTERS.  When  an  applitatioil  first  starts  up,  the  dehmlt  prefix  identifies 
the  name  of  the  Imat  volume. 

As  indicated  ill  tablt  IQ-l,  ProDOS  16  li^  a  sijnilar  shorthand  notation  for  the 
prefixes  desLribing  eigbt  other  directories.  Only  0/  and  3/  to  7/  stiould  be  changed 
by  an  jipplieation.  althouffh  it  is  pos-iible  to  LhaiiRe  1/  and  2/  if  you  reiihy  need  to. 
Change  prefixes  with  the  SET.PREFJ.X  eomiriiind, 

THE  STRUCTURE  OF  A  PRODOS  16  BOOT  DISK 

Certain  files  mn.sl  he  present  on  a  ProDOS  16  system  disk  before  vou  can  boot  [t 
or  nse  it  to  nm  both  ProDOS  H  tind  ProDOS  16  applieations.  The  structure  of  tlie 
simplest  sueh  system  disk  is  as  follows: 

PR  D  DOS  Operating  system  Itwder 

SYSTEM/  SulKlireetoTj';  operating;  system  Files 

P8  The  ProDOS     operiltin^^  syste  m 

P  1  G  The  ProDOS  IH  oiwrating  sysfem 

START  Th  e  stwrl-up  prngram 

TOOLS/  Subdireeturv:  R^M-based  tool  sets 

FONTS/  Subdirectory-  ffint  files 

DESK  .  ACCS/  Snbdireetnrx:  desk  iiefessoric'S 

LIBS/  Snbdireetorv-.  sy-iteni  libmiy  files 

DR  I  VERS  /  Sii}>direeli)ri':  devite  drivers 

SYSTEM. SETUP/  Snbdirettiir>-:  iiiitialization  prof^ram'i 
TOOL  .  SETUP  Patches  to  ROM-b;med  IoliI  sets 


A  ProDOS  16  system  di^k  goc5  throo^;h  a  ratlier  Lonvoluted  start-up  procedure 
when  yim  boot  it.  It  begins  by  lo^idin^  the  PrcifJOS  pm^rLini  into  nieinury  a-iid 
exeeulin};  il,  Oneo  ProDOS  sets  tontrol  it  loads  the  ProDOS  16  opt-ratitig  system 
from  the  -SYSTEM/Flfj  file  and  then  e^ceeutes  the  TOOL.SETL'P  program  in  the 
SYSTEM/SYSTEM- SETUP/  directory.  TOOL.SETUP  piitches  and  enhances  ROM- 
based  toil]  sets. 
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Table  JO-1:     Standard  Prtrfix  Nunil>pr!i 


Prefix 

Nu  mher  De.tcript  io  n 

*}  Tilt  bout  prffix 

TIsis  is  tlif  v'lilunR'  numt;  fnini  which  ProHOS  16  was 
bootf  d-  Thii  prtKx  cminat  be  chunked. 

0/  The  defiitdE  prefix 

ProDOS  automiilic-dlly  attatht-s  it  to  any  filenajjic  or  [wrtial 
pathname  (as  opposed  to  fuU  pjithnamel  you  specify. 

17  T]ie  appliciilinii  prfhii 

Tlu'  piithnunit  ot  ihe  directory-  cuntaining  (he  tuirent 
application  program, 

2J  The  system  libran  prePiK 

The  pathname  of  the  directorv'  conCaining  lihrar>'  modules 
usvcl  bv  ihu'  lurrtiil  application.  For  a  standard  FruDOS  16 
ht.(>t  disk,  this  is  /MYDESK/SYSTEM/LIBS/. 

3/  User-definable 

4/  User-dcfinahlip 

5/  User-definalile 

6/  L'str-dthnable 

7/  U  ser-de  fill  lib  le 


ProDO.S  then  tnntinncs  hy  Ifvading  and  executing  every  other  file  in  the  .SYSTEM/ 
SYSTEM. SETUP/  directory.  Typical  files  include  permanent  initialization  (.itart-up) 
files  with  file  t^  pc  codes  of  SBfi  and  temporary  initiilizatinn  files  with  file  t^^ie  rades 
ol'SBT.  The  diflercnce  Iwtwecii  these  two  types  of  files  is  that  temporary  initialization 
files  remove  themselves  from  memnrj'  when  they  finish  executing;  permanent  ini- 
ti^izutinp  fill's  do  not. 

ProDOS  then  moves  to  the  SYSTEM/DESK. ACCS/  directory  and  loads  into 
memory  any  Classie  Desk  Acee^sory  files  [file  type  SB9)  and  New  Desk  Accessory 
files  (file  t\pe  SBK),  This  eau.iies  the  names  of  the  Classic  Desk  Accessories  to  be 
placed  in  the  menu  that  appear^!  when  you  press  Control-OpenApple-Esc, 

Next,  FroDOS  searches  the  SYSTEM/  director>^  for  a  file  called  START  that  has 
a  flic  type  of  $B3  (S16).  If  it  finds  this  file,  it  loads  and  executes  it  and,  the  boot 
process  ends.  The  START  program  is  typically  a  prograin  selector  that  lets  you 
choose  a  particular  application  to  run. 
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If  PRODOS  does  not  find  START,  it  scans  the  volume  director)'  unEd  it  finds  a 
ProDOS  8  syslt'Tii  program  {file  type  SFF)  whosr  name  t-nds  with  ".SYSTEM"  Or  a 
PruDOS  l(j  systf  in  progriiin  (file  type  $B"i)  whcwe  name  t-nds  with  ".SYSie."  Il  then 
ends  the  boot  procedure  by  running  the  program.  It  will  nut  run  a  ProDOS  8 
progfiiin  nnkss  SYSTEM^PH  i?;  nn  thr  disk,  tinwcvir.  If  no  such  system  program  is 
Fniiiid,  PBODOS  brings  np  a  window  asking  thf  user  tu  enter  the  pathname  of  the 
application  to  run. 

USING  PRODOS  16  COMMANDS 

The  s^neral  procedure  for  calling  a  ProDOS  16  command  is  different  fri»iii  the  one 
Uied  to  call  a  tool  set  luiiction.  It  goes  something  like  this: 

JSL  lEIOOAE  iCall    ProDOB    IB  entry  pcHit 

DC  1  2  '  CommaTidHjm  '  jCiimmand  TiLimber  [word] 

DC  l-l'ParmTable'  ;  Address  of  parameter   lable  [longl 

BCS  Error  ifContrDl   rESLimes  here  after  call) 

Yolt  cati  call  a  PmDOS  16  command  whilr  the  651iil6  is  in  native  mode. 

Immediately  Ibllowing  the  JSL  instmetion  is  a  word  L-untainin^  tlje  idealiflt"dtioM 
iiiJm!)er  of  the  ProDOS  lii  command  yon  wish  to  use.  Table  10-2  contains  a  list  of 
all  32  ProDOS  Hi  eoniniiinds  ;iml  command  nuinhers. 

Followlntt  the  command  nnmber  a  pointer  to  a  parameter  table  containing 
parameters  rrtiuirtid  hy  the  command  and  resiilts  returned  by  the  command.  The 
parameters  can  lie  one-  or  two-word  uonieric  values  or  two-word  pointers.  The 
exact  structure  of  the  parameter  (able  varies  froin  c-ommand  to  command. 

When  a  ProDOS  16  Li»mmand  finishes,  it  adds  6  to  the  retnni  address  pushed 
oji  the  stack  by  the  JSL  instruetidn,  iheii  ends  with  an  RTL  instruction,  This  causes 
contrnl  tu  pass  to  the  code  hegiiioiog  just  after  the  pointer  to  the  parameter  table. 
On  return,  alt  registers  retnain  unchanged  exiept  the  accumulator  (which  contains 
an  error  code),  the  program  counter,  and  the  status  register  (the  m.  x.  1,  and  e  tJags 
are  unchanged;  N,  V,  and  Z  are  undefined;  the  D  flag  is  cleared;  the  carry  Hag 
reHects  the  error  status). 

At  thi5  stage,  you  can  check  the  state  of  the  carry  flag  to  df'termine  whether  an 
error  occurred:  if  the  carry  flag  is  clear,  there  was  no  error;  if  it  is  not  clear,  an  error 
did  occur  .^n  error  code  indicatinj;  the  nature  of  the  error  comes  back  in  the 
accumulator;  the  accumulutur  will  contain  0  if  no  error  occurred.  See  table  RlO-2 
in  the  reference  section  at  the  end  of  this  chapter  for  a  list  of  PtoDOS  16  error 
codes. 

APW  cornes  with  a  set  of  macrns  which  will  help  to  simplify  the  use  of  a  ProDOS 
16  command.  They  are  stored  in  a  G!e  tailed  V116.PH0DOS.  To  call  a  ProDOS 
command  with  a  macro,  use  instructions  cif  the  form; 

CMDNAME  ParmTbi 
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Table  10-2:    The  ProDOS  16  Commands 


Comrimnd  dumber    Cummand  Name 


Description  of  Commimd 


m 

$02 

$05 
306 

m 

SOA 

SOB 

SIO 

Sll 

S12 
$13 
$14 

$15 

$1B 

$17 

$18 
$19 


CREATE 
DESTROY 

change.path 

set_file^ixfo 
c;et_file_tnfo 

VOLUME 

SET_PREF1X 

GET_PKIiFLX 

CLEAR_BACKUP_BIT 

OPEN 

NEWLfNE 

READ 

WHITE 

CLOSE 

FLUSH 

SET_MARK 

GET.MARK 

SET_EOF 
GET  EOF 


Creates  a  new  Rle 
Deletes  a  iile 

Renames  a  file  or  moves  it  to 
another  directory 

Changes  the  iittnbutes  of  a  file 

Returns  the  attributes  of  a  file 

Retiirnj^  the  name  and  attributes  of 
thf  volume  in  a  device 

.Assigns  a  pathimmc  prefix  to  one  of 
the  eight  standard  prefix  niimherS 

Returns  the  pathname  prefix  for  one 
of  the  eight  standard  prefix  numbers 

Clears  the  "hiiekiip-needed"  bit  in  a 
file  S  aeteSS  eude  byte 

Prepares  a  file  for  subsequent  rtad. 
write,  and  pusitianin^  oominartds 

Sets  the  end-of-line  character  for 
read  opemtions 

Reads  dafa  from  an  open  file 

Writes  data  to  an  open  file 

Prevents  aceeas  tn  a  file  until  it  is 
reopened 

Writes  the  (.contents  of  the  file's  I/O 
buffer  to  disk 

Sets  the  active  position  in  an  open 
file 

Returns  the  active  position  in  an 
open  file 

Sets  the  size  of  the  file 
Returns  the  size  of  the  file 
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Table  10-2:  Coiititiucd 


Cotninatid  Number   Command  N/imr 


Description  of  Ctnmnand 


$JB 
520 

$22 
$33 
$24 
$27 

$28 

$29 
S2A 
S3 1 
$32 


SET^LHVEL 

GET„LEVEL 

GET_DEV_.\UM 

GET_LAST_DEV 

READ. BLOCK 
WRITE.BLOCK 
FORMAT 
GET.NAME 

GET.  BOOT.  VOL 

QUIT 

GET.  VERSION 
ALLOC_[NTERHUlT 
DEALLOC  INTERRUPT 


Sets  thp  system  file  level 
Returns  the  system  file  level 

Returns  the  number  of  a  named 
device 

Returns  the  number  of  the  last 
device  accessed 

Reafls  a  block  of  data  from  a  device 

Writes  a  block  of  data  to  a  device 

Formats  the  medium  in  a  device 

Returns  the  filename  of  the  eurrent 
application 

Returns  the  name  of  the  ProDOS 
booi  volume 

Exits  the  current  appLication 
Returns  the  ProDOS  version  ftumbei 
Installs  an  interrupt  handler 
Removes  an  interrupt  handler 


where  CMDNAME  represents  the  name  of  the  command  and  ParmTbl  represents 
tlie  address  of  the  parameter  table  associated  with  the  cnmmsnd.  At  assembly  time, 
this  macro  is  expanded  hilo  the  standard  ProDOS  16  calling  sequent*. 

The  main  advantage  of  ushig  the  macros  is  you  do  ncvt  have  to  memnrize  Ltimmand 
numbers,  only  command  names.  It  also  ma.kcs  a.s!icinbly  lan^uajie  programs  that  use 
ProDOS  16  a  lot  easier  to  read. 

In  tbc  sections  which  follow,  parameter  tables  for  FroDO!>  16  commands  are 
presented.  These  tables  desLribe  the  order  of  the  parameters,  the  size  of  the 
parameters,  and  whether  the  parameter  is  an  hlput  (1)  or  a  Residt  (R),  An  Input  is 
a  parameter  that  must  be  pnivided  before  using  the  command.  A  Rfsult  (R)  is  a 
parameter  returned  fn'  the  LDmmand. 

Note  that  even  lliuufih  a  pointer  to  a  string  may  be  marked  as  a  result.  ProDOS 
16  does  not  actually  return  the  pointer.  Instead,  it  rctoms  the  bytes  in  the  string 
in  the  space  pointed  to  by  the  pointer  It  is  the  responsibility  of  the  application  to 
allocate  a  space  of  the  proper  size  and  to  provide  a  pointer  to  it. 
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FILE-MANAGEMENT  COMMANDS 

The  PruDOS  filtf-inanagement  commands  perform  a  variety  of  important  operations 
on  dosed  files; 

•  Creating,  destroying,  and  renaming  files 

•  Reading  and  ctiangiiig  file  attributes 

•  Reading  and  changing  palhname  prefixes 

The  firsl  tiA'o  groups  of  commands  affect  only  the  directon'  entry  for  a  file,  not  the 
data  inside  die  file. 

Crcdtin^  New  Files 

The  file  mana^pmenl  command  you  will  probably  use  most  often  is  CREATE,  With 
it  you  Lan  create  a  directory  entry  for  a  data  file;  you  can,  subsequently  open  this 
file  and  write  data  to  it.  You  can  also  use  CREATE  tn  create  5iibdirector\'  files. 

The  paj-amcter  list  for  CREATE  is  quite  lenp;thy,  because  it  must  contain  all  the 
attributes  for  the  file.  Here  is  how  it  is  structured; 


CREATB  ($01) 


Offset 

Symbolic 

Input 
or 

Result 

Description 

+0  tQ  +3 

pathname 

Pointer  to  the  pathname  itring 

+4  to  +5 

access 

Access  code 

+6  to  +7 

file_type 

Fde  type  code 

+8  to  +11 

auK_type 

Auxiliary  type  code 

+  12  to  +13 

storaKe.type 

Storage  type  code 

+  14  to  +J5 

create_date 

Creation  date 

+  16  to  +17 

t:reate_time 

Creation  time 

Every  item  in  the  CREATE  parameter  list  is  an  input  parameter,  so  each  must  be 
set  up  properly  befnre  calling  CREATE,  Multibyte  items  arc  stored!  with  the  low- 
order  b>  tes  first,  usual. 
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There  are  many  iinifainiliar  items  in  this  paramptor  libt  that  require  fiirther 
expkniltLHn;  tht;  same  items  appear  in  tlie  parameter  tables  of  maiiy  other  PrmDOS 
16  commands.  Each  item  is  esamined  in  detail  belnw. 

Pathname.  This  Hem  is  the  address  ufa  pathname  string  identifying  tlie  file  to  be 
crt^ated,  The  string  htj^ins  with  a  length  byte  and  i.s  ibllowed  by  ASCII-enmded 
cJiaractcrs. 

Access.  The  aecess  item  indicates  whether  the  file  may  be  read  from,  written  to. 
renamed,  or  de.stroyed,  it  ai.n  indieates  wliether  the  file  has  been  modified  sinc^ 
the  last  hack-up  operation,  Only  the  Uiw-order  byte  of  act:en^  is  defined  [the  hi^h- 
order  byte  is  0)^  the  meaning  of  each  bit  is  as  fullows; 


7  & 

5       4       3  2 

1  0 

D 

RN 

B 

[reserved] 

W 

R 

The  abbreviations  in  this  chart  have  the  following. meanings: 

•  n    =  delete -enabled 

•  HN  ^  rename  .enabled 

•  B     =  back-up  required 

■  \V    =  wrile-enabled 

■  R    =  rDad-eiiabled 

The  access  attribute  for  a  particular  bit  is  enabled  if  the  correspond iiifi  bit  is  1;  if 
the  hi[  is  0,  the  yttributo  is  disabled. 

When  LTcatins  standard  file',,  with  lull  access  pernntted.  set  access  tu  SE3.  If 
some  of  tlie  access  attributes  are  disabled,  the  i\]e  is  said  to  he  lucked, 

PrnDOS  Ifi  aulomatii.alIy  sets  the  batk-lip  bit  to  1  whenever  you  write  to  the 
file  to  inform  a  back-up  utdit>  program  that  [he  file  has  changed  since  the  last  batjk- 
up.  rt  is  the  responsibility  of  the  iiatk-up  to  clrar  this  bit  to  0  with  the  CLEAR. 
BACKUP_BiT  command  after  making  the  back-up. 

FUeJyfje.  Tht  low-order  bvte  of  the  file  type  code  indicates  the  general  nature 
oi  the  data  the  file  contains.  (The  hijjh-order  byte  is  sJways  0, )  A  liit  nf  the  commonly- 
used  codes  is  pnivided  in  table  lU-3. 
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Table  10^1: 


Pro  DOS  16  File  Type  Codes 


File  Type 
Loae 

Slandurt! 
M  nemonic 

Description  nf  File 

900 

Uncatcgorizeil  file 

101 

BAD 

I3ad  block  file 

|0S 

PCD 

Pascal  L-adv  (SOS) 

$03 

PTX 

Pascal  test  (SOS) 

$04 

TXT 

ASCII  textfile 

PDA 

Paardl  dafa  (SOS) 

BIN 

General  binary  file 

FNT 

Font  file;  (SOS) 

$08 

FOT 

Graphics  screen  file 

Ann 

BA3 

Business  BASIC  program  (SOS) 

DA3 

Business  BASIC  data  (SOS) 

IDE 

WPF 

Wurd  processor  file  (SOS) 

$OCi 

SOS 

SOS  system  file 

$OI>--S0E 

[Reserved  for  SOS] 

•OF 

DIR 

Subdirecton^  file 

$10 

RPD 

Record  Processing  System  data  (SOS) 

HI 

RFl 

Record  Processing  System  index  (SOS) 

$12 

AppleFile  discard  file  (SOS) 

»13 

ApplRFile  model  file  (SOS) 

$14 

AppleFilc  report  format  file  (SOS) 

415 

Screen  libran-  file  [SOS] 

$16-S18 

[Reserved  for  SOS] 

$19 

ADB 

AppleWorks  di^tabose  file 

SIA 

AWP 

AppleWorks  Wiird  processinj;  file 

SIB 

ASP 

ApplcWnrks  spreiidsheet  file 

S1C-$AF 

[Reserved] 

SBO 

SRC 

APW  source  codi^ 
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Table  SO-3:  ConMinied 


^iiin/i/ii'ti 

IJ  m  11-4  1 1-IU  f  \A 

Code 

Mnemon  ic 

Desoipiiaii  of  Fih 

$B1 

OBJ 

ISB2 

LIB 

APW  librarv' 

SRI 

$B4 

RTL 

FXF 

A^^^^^  f'i'f  j^i  1 1"^  1  ii I hf  1 1  i4  nil  1 1'T'sihir  1  n 

(m L   TV    CA^'U  ULaLJ^iL    ^  1 1^ IJ  uLJIJ ll^uL  11  JliL 

■p  LflJ 

Prf  1 1  ^iT         1 A  n4^mi  Qn       P  in  lit           T~t_i  i  n  n  "R 
P  1  U  LJ\J  J    IW  lltTi  lllilllCllL  IIJIL  ^aliU  L'ULI/  llillT 

1 13  r 

Fr-t]13()S  16  tt?iiiponJrj'  init  file 

u4  It   1  But'  ir        "-f » J*' J ■  ■» j"i p 

TOT 

1  UEJJ  ■7'trl 

ri\jj_'\/i3'  iKf          ii.tr  LirLVi  i 

SRC]— SIR  F" 

$BF 

doc: 

PrtiDOS  IS  document  file 

PNT 

1    n  iTiTiPfi  cuntfi    CI  VT'U'ki'  n  icTri   ^t^c   tii  rvri  ■'^O   n  1 

$Cl 

PIC 

1  R'P'Crfirv'iPfi  1 

$C8 

Pi-nDOS  18  Fnnr  RV 

&C9-SEE 

[Reserved] 

SEF 

PAS 

Pascal  area  on  a  partitioned  disk 

$F0 

CMD 

ProDOS  8  added  coiininand  file 

$F1-$F8 

PruDOS  8  user-defined  files 

ijir  a 

Pi6 

ProDOS  16  file 

$FA 

INT 

Integer  BASIC  program 

$FB 

JVH 

Inte^ier  BASIC  varialjles 

SFC 

BAS 

Applesoft  BASIC  prograin 

$FD 

VAR 

Apple.sdft  BASIC  variables 

$FE 

REL 

EDASM  rclncatabU"  code  file 

$FF 

SYS 

ProDOS  S  S);stem  program 

NOTE;  SOS  5 

MfiAi  for  the  Apple 

III  SoLihi^tK-at^  OptrdtinB  System 

340  The 

ProDOS  16  Operatinfi  Si/sfem 

Auxjffpe.  The  meaning  of"  tlie  auxiliary  type  code  for  a  file  depends  cm  the  file 
iypv  code.  A  (estiile,  for  cxtunple,  u^ea  iht-  uTjxiliary  typi:  aide  to  iiidicale  the 
random -access  record  Iciigfh  (or  0  for  a  seqiimtial  textfilt  not  divided  into  separate 
^t«l^d^)-  APVV  u!«t's  thr  :uis_tvpe  code  in  SRf:  (SBO)  files  to  hold  a  Iansiiaj>t-  ID 
number-  Mute  that  cmly  the  low-order  word  of  aiix.tvpe  is  preseiitJv  used  by  PruL>OS 
16. 

Storage  JyiiF.  The  low-order  In  te  of  the  storase  tvpc  tjode  indkates  thf  structure 
of  the  file  on  the  disk.  The  possible  values  are: 

SOO         Inactive  en(r\' 

m        .Seedli^j^  file  (EOF         512  hytes) 

802       Saplins  file  (512  <  EOF  <=  laSK  bytesj 

.?03       Tr<:-e  file  {l^SK  <  EOF  <  16M  bytes) 

S04        Pijseal  reyioii  un  a  partitioned  disk 

SOD       Subdirectory  file 

$flE       A  ^inbdiretton,'  ^eader 

("OF      A  voIuKie  directory  header 

TTie  difl'erenccs  among;  a  st<'d|ing,  a  sapling,  and  a  tree  file  are  really  not  important 
to  the  deiigncr  of  an  apidication  prnfirjim,  JinfRtc-  to  say  that  all  standard  data  files 
should  have  a  storage  type  of  Wl  (scedlinp).  as  file  jjirows  in  size,  PmDOS  16 
autninutically  changes  its  struttiire  into  that  of  d  sijpliiij;  file  and  then  into  a  tree 
file.  For  a  deseripTion  of  thest-  three  basic  file  stmt  tiires,  refer  tii  Afipte  ProDOS.- 
Adiaitctii  Ft'ahiifxfor  Pronruinincrx  (Litllt,  1985).  If  you  are  creating  a  subdirectory 
file,  sc'l  storast;_tyix>  to  ^OD. 

Creat€_ditt€.  The  creation  date  is  a  Iwu-byte  value  containiiiji  the  year,  month, 
and  day  on  which  llie  file  was  created.  The  encoded  formats  of  thr.^e  three  quantities 
are  as  followji: 


15  14  13  12  1110  9 

 1  1  *  1  1  .— - 


8  7 


year 


e  5 

-I- 


month 


3  2 


day 


I  0 

^ — I — 


If  you  specify  a  creation  dale  of  U,  PruDOS  16  aulomatiadly  uses  the  cuLrrent  date. 


Create  Jime.  Tlic  cre  ation  time  is  a  two-bj'le  value  containing  the  hour  and  minute 
on  which  the  fik'  wa^  created,  These  twti  (jitanlitie.-.  arc  encoded  ai  follows; 
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15 

14 

13 

12  1110  9  8 

7 

6 

5    4    3    2     1  0 

0 

0 

0 

 1  1  1  *  1 

hour 

0 

0 

 1  1  1  1  1  

minute 

if  you  specify  a  LTeatiun  limt"  of  (J,  FriiDOS  16  auttimati tally  uses  thr  ciirrenl  time, 
DtU-tiiLK  Files 

Tu  removi'  li  file  from  its  directory  periiianendy,  you  irnist  delete  the  file  with  the 
DESTROY  c-(imnmiid  Destroying  a  file  also  frees  up  the  disk  blucki^  used  hy  [he 
file,  making  thcni  available  for  allDCiitioii  to  other  files, 

The  (inly  item  in  the  DESTROY  parameter  list  is  a  pathname  pointer; 

DESTROY  ($02J  

input 

Ojfiel  Sam*:  Result  Description  

+0  to  +3  pathname  1  Pointer  to  the  pathname  string 

Nntp  that  ynu  cannot  destroy  a  file  if  the  delete- enabled  bit  in  its  access  Lode  is  0. 
You  tan  use  SET_FJLE_l,NKO  Uec  lielow]  tti  set  this  bit  prior  to  deitruving  a  file. 

Renaminj;  File; 

The  most  cwmtnon  use  for  the  CHANGE_PATfl  command  is  to  rename  a  file,  hut 
it  is  also  T-iheful  liir  mtivinK  ;i  file  frnm  one  subdirectory  to  another  on  the  same  disk. 
Its  paramt?ter  table  looks  like  this; 

CHANGE_PATil  (S(I4I 


Injnil 

Symbolic  tir 
Offtei  Wime  Rmult  DetitriptipTt 

+0  to  +3        pathname  I  Pointer  to  the  ]iathname  string 

+4  to  +7       iiew_pathname         I  Pointer  to  the  new  pathname  slrinj^ 
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When  (he  two  pijthniiiiie^  specified  are  ideiiHcal  fxcept  for  the  Eilt-name  portion, 
CHANCtE_FATH  simpK  rehLimes  the  file.  If  th^f  pathiiiunss  describe  files  in  differ- 
ent dirt-cldries.  tlif  enlry  for  lh<-  fik'  in  tlu'  fiist  dirfi'torv'  spodfifd  is  movi'd  tu  thu 

Note  that  you  camiol  rtiiiuiu'  a  fih-  iJ  the  rename  L-iuibled  bit  in  its  access  ctide 
is  0.  You  can  use  i>ET_FlLE_[NFO  ^s^'e  helow)  Itj  set  lliis  hil  prior  to  rcnaminy  a 
file. 

Changtug  File  Attributes 

As  wiis  disLussed  in  the  r>(a  mi  nation  of  the  CKKATE  mimnund.  each  filtf  ii  iij^^ociated 
with  A  'ifl  of  attriljuilt'S  thul  lU^cribor  sueli  ^hiTl^^s  as  ihe  dwte  and  time  tin  whith  llie 
file  was  {.Teated,  the  file  type,  the  aujiiliar.'  t>  pe  code,  and  sn  on.  You  van  determine 
what  these  pttrameler's  are  tor  any  esistii^j;  file  usiriK  the  C;ET_FILE_lNr'0  loiji- 
niimd.  Here  is  what  its  piariineter  tal»]e  l(K)ks  like; 


rTET_FILE_]NFO  (SOB) 


Offset 

Symbolic 
\'ame 

Input 
(ir 

Description 

+0  to  +3 

pattiniime 

1 

Painter  tu  the  piLthname  string 

+  4  to  +5 

ateess 

R 

Atcess  code 

+6  to  +  7 

filc_t>'pe 

R 

File  type  code 

+8  to  +11 

aiix_type 

R 

Auxiliary'  type  code' 

+  12  to  +13 

storage,  type 

R 

Storage  type  ende 

+  J-1  to  +15 

ercale_iJa(e 

R 

Oeation  date 

+  16  to  +  17 

LTeale^tiine 

R 

Creation  time 

+  18  to  +19 

mod  _  date 

R 

ModiEcatinn  date 

+  20  to  +21 

mod_tiide 

R 

Modihtation  time 

+22  to  +25 

bIoeks_used 

R 

Blocks  used  by  the  file 

'  For  a  TiTjIumt 

direi-lon'  filu.  [Ilis  fidd  liecfiiiH 

S  til[ill_l)]Dcks 

Itlif  numbiT  of  blwks  oh  the  voluaie). 

The  only  input  parameter  is  the  pathname  deseribing  the  file  you  want  to  examine. 
All  other  parameters  jure  returned  hy  CET_FlLE^lNFO. 
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The  last  three  (ypes  of  parameters  in  the  chart  above  have  not  been  discussed 
yet: 


Mod_date.  The  date  on  whiL-h  the  file  wai  last  nmdititd.  Tht:  format  ul"  this 
word  is  (hq  sa^ne  as  that  fur  crtt3tt'_date. 

Mod_th7ie.  The  time  at  which  the  file  was  last  modified.  The  format  of  this  word 
is  the  same  as  that  for  CTeate_ttnie. 

Blochs_used.  The  total  nunihcr  of  blocks  used  hy  the  file.  It  indudes  ajiy  non- 
data  blocks  used  as  overhead  hy  the  operating  system. 

The  results  returned  b>  CET^FILK.lNFO  are  slightly  diiferent  if  the  pathname 
points  to  the  n±n\c  of  the  vulnmc  directory  of  the  disk.  In  this  case,  the  auK_type 
field  contains  the  size  of  tht^  disk  in  blocks  (eallt-d  total  bhtkN)  and  the  blueks^used 
field  eontains  the  total  number  of  blocks  used  by  all  files  on  the  disk, 

Yotl  c-aji  use  a  related  eommand.  SET_FILE_INFO,  to  thange  the  attributes  of 
any  file'  its  parameter  table  looks  just  like  the  one  used  for  GET_FlLE_I VFO, 
except  that  it  docs  not  include  the  block&_used  field  al  the  end-  An  easy  way  to 
change  one  partieular  file  attribute  without  atleetmg  the  rest  is  to  call  C.ET_F£LE_ 
INFO,  store  the  new  parameter  in  the  GET_FILE_INFO  parameter  table,  and 
then  call  SET_FiLE_I.\FO  using  the  same  parameter  table.  Note,  however,  that 
you  cannot  change  the  storaRe_type  attribute  with  SET_FILE_IXFO. 

Note  thiit  SET.FILE^INFO  Lannot  he  ii.^ed  to  clear  the  back-up-needed  bit  of 
the  access  code  word  This  bit  is  primarily  for  the  benefit  of  disk- back- np  utilities. 
By  examining  the  bit,  such  utilities  can  determine  if  a  file  has  changed  since  the 
last  baek-up.  After  the  back-up  operation,  the  back-up  utility-  should  dear  the  back- 
op  bit  tu  0.  Tn  do  thii,  It  must  use  the  CLEAR_BACKUF„BIT  command.  Here  is 
the  structure  of  the  parameter  table  ihr  CLEAR_BACKUP_BIT: 


C  L  E  A  K_  &AC  K  IT  P  _  B I T  [^B) 


Infjut 
Symbolic  or 

Offset  Name   Resyli  Descriplion  

+  0to+3  pathname  I  Pointer  to  the  pathname  string 


Notice  that  all  you  have  to  specily-  is  a  pointer  to  the  pathname  string. 
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Deter  III  ining  Volumt;  Characlcri^tics 

The  VOLUME  tan  lie  used  to  determine  some  of  the  characteristics  of  a  disk 
Volume: 


VOLUME  ($08) 


Input 

Symbolic 

or 

Offset 

Name 

Result 

Descriptititt 

+0  to  +3 

dev_nam(: 

I 

Pointer  to  the  device  name  striiit^ 

+4  to  +7 

vol  _  name 

R 

Pointer  to  the  volume  name  string 

+S  tn  +  1 1 

total  _blocks 

R 

Size  of  the  voJume  in  blocks 

+  12  to  +15 

free_hlocks 

Ft 

Number  of  unused  blocks 

+  16  to  +17 

fil'e_syi_id 

R 

Operating  ,sy.'stem  ID  code 

Tlic  VOLUME  command  takes  one  input  parameter — a  pointer  to  the  name  of  the 
device  (dev_iiaine) — and  rtf turns  infuriTiatiiin  respecting  the  volume  in  that  device. 

Dev_name  points  to  a  string  of  the  form  .Dn  that  is  preceded  by  a  length  byte. 
The  value  for  n  can  be  frojn  1  up  to  the  number  nf  PrtjDOS  blwk  devices  in  the 
system.  The  only  way  to  determine  the  maximum  value  for  n  is  to  call  VOLUME 
with  consecutive  device  names  until  error  Sll  (invalid  deviee)  occurs. 

Voi^name  is  a  J7-byte  bufler  area  in  which  VOLUME  return.s  a  length  byte 
followed  by  the  name  of  the  volume.  The  name  of  Uie  volume  includes  a  leading 
slash  {/)■ 

The  other  values  returned  are  as  follows: 

total_biocks.  The  total  number  of  blocks  on  the  volume. 

free^bloch.  The  total  number  of  ynused  blocks  on  the  volume, 

JHe_sys_tf!.  The  low-order  byte  iif  thiji  word  indicates  the  type  of  operating 
svitcm  to  which  the  device  belongs.  The  possible  results  are  as  follows; 

■  1  =  ProDOS  or  SOS 

■  2  =  DOS  3.3 

■  3  =  DOS  3.1  ur3.2 

■  4  ^  Apple  II  Paseia] 

•  5  =  Macintosh  (flat  file  structure) 
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•  6  —  Maciiitoiih  [HFS;  hierarchical  file  structure) 

•  7  =  Macintosh  XL 

•  H  -  Apple  CP/M 

All  nther  values  are  reserved.  Version  U  of  Pro  DOS  16  recognizes  only  Pj-ciDOS 
and  SOS  disks,  however  (filt  __s.y]5_id  —  \K  If  il  detects  afiolher  lV'|>e  of  disk,  it 
returns  an  error  code  of  $52  (unsupported  volume  tv-pc). 

The  other  common  error  codes  that  VOLUME  might  return  are  as  follows; 

$27  I/O  error;  this  error  is  reported  if  there  is  no  disk  iin  a  S'/i-incih  drive. 
S28       No  devlL'e  conntcted;  this  error  occurs  if  you  do  not  have  a  fecund  5Vj- 

inch  drive  coriEiected  to  the  drive  contrnKcr. 
S2F      Device  not  on  line;  tliis  oct-urs  if  (here  is  no  disk  in  a  31^-iuch  drive. 

ManipuluHng  Prefijces 

Earlier  in  this  chapter  you  saw  litiw  useful  prcfi^c?  can  be,  ProDOS  16  lets  you 
define  eight  different  prefixes,  whicli  can  he  referred  to  by  the  prefix  designator^ 
Q/.  1/,  2/.  3/,  4/,  5/,  6/,  and  71.  As  explained  earlier,  the  first  three  prefixes  are 
reserved  fiir  the  system  subdirectory  {0/),  the  appIic::itLon  subdirectory  (1/),  and  the 
library  iubdirettnry  (2/), 

The  prefixes,  from  3/  to  7/  arc  not  used  in  any  special  way  by  the  operating  system, 
so  applications  can  use  them  tn  identify  any  direetnries  they  wish-  For  example,  4/ 
could  be  a  direetor\'  containing  help  files  and  5/  could  he  a  directory  containing  data 
Hies  for  &n  application. 

Use  the  SET_FREFIX  Liimmand  to  assign  prefix  strings  to  the  eight  standard 
prefixes.  The  parameter  table  louk;,  like  this; 


SET_PftEFL\  (.'SOS) 


Offset 


+  0  to  +1 
+  2  to  +S 


Stjmholic 
Name 


prefix_nuni 
prcR»: 


Input 
or 

Remit 


Dejicriptiun 


1  Prefix  number  (0  tu  7) 

i  Pointer  to  the  new  prefix  string 


Both  these  parameters  are  input  parameters.  The  stritij;  pointed  to  by  prefix  begins 
with  a  length  byte,  which  is  followed  by  die  ASCII-encxided  characters  in  the 
director.'  pathname,  If  the  prefix  string  is  not  preceded  by  a  slash,  the  string  is 
appended  to  the  current  prefix  to  create  the  new  prefix  string. 
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The  GET.PREFIX  ijaramcter  talilc  Inoks  like  thi^; 
CET^PRKFIX  (SOA) 


li\pitl 

iiijmhotic  or 
Offset  Name   ResuU  DescripHon  

+0  to  +1  prefix_num  I  Prefix  number  {0  to  7) 

+2  to  +5  prefix  R  Pointtrr  tc;  prefix  name  string 

Use  CET_PHEFIX  tu  determine  the  current  settings  of  the  standard  prefixes.  It 
returns  the  result  in  a  buffer  pointed  to  by  the  prefix  parameter.  The  result  is  a 
length  byte  fnlkiwtd  by  the  prefix  name,  T3ie  uaine  is  preceded  and  rnMnwec!  by 
slashes  ('f'].  Vuu  niusl  idlueale  a  bufler  67  bytes  to  atcominodate  the  largest  prefix 
niime  that  nii^bt  be  returned. 

FILE  I/O  COMMANDS 

The  file  I/O  cnminamls  afii  L  l  tlir  data  portion  of  a  tile,  Tlie  two  main  coinmand.'i  an 
iipplitatiun  uses  M  f  tor  reatJin^;  and  wriiin;;  Reading,  ol  c-ourse.  \i  lilt  transfer  of 
data  from  disk  to  inemnT  y,  writinf;  invub  es  a  transfer  in  the  opposite  direction. 

Pu!iitiDns  in  the  File 

Before  tlie  file  MO  eoinmand.s  iire  e.xamined,  t^m  im.portant  con»N?pts — mark  and 
EOb — iiibould  be  inenljoiifd- 

Thf  position  within  a  file  at  whiob  a  subsequent  read  or  write  nperation  will  take 
plaiLif  is  Lidled  the  mark  pofiition.  As  you  a«-ess  bytes  in  the  file,  the  mark  pn-s,ition 
keeps  iiiereinentiTii^H  mi  it  is  alwitys  pointing  to  the  nt'?il  byte  to  be  aueessed. 

When  you  oi>eii  a  file  prior  to  reading  from  it  or  writinj;  to  it,  ProDOS  16  sets 
mark  to  0,  meaning  thiit  suhst'(|iieiit  operations  will  take  plaee  nt  the  beginning  ol 
the  file.  (The  bytei  in  a  file  are  nmnbfred  friiin  ()  |  As  wdl  be  shown  later  in  tins 
chapter,  it  is  easy  to  skip  to  any  other  position  in  the  fUe  using  the  ProDOS  f6 
SET_\[ARK  eominand. 

The  other  importiint  position  iwramttcr  is  EOF,  EtJF.  which  stands  for  "end-of- 
Rle,"  contains  the  size  ol  the  file  in  bytes,  so  it  can  be  tbouglit  of  as  a  pointer  to  the 
byte  past  the  la.sl  byte  in  the  file.  EOF  dutomutieallv  increases  as  you  write  data  to 
the  end  ol  the  file.  You  e;in  ineretLSe  or  decrease  EOb"  esptieilly  with  the  SET_EOF 
eommand. 
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Reading 

To  read  data  from  a  file,  you  must  perform  the  folJowing  steps: 

1,  Open  the  flip 

2,  Move  the  mark  positmn  (if  necessary) 

3,  Adjuiit  ncwliiK-i  iiiudf  (U' necessary} 

4,  Read  the  data 

5,  Close  the  file 

You  can  read  only  from  a  file  whith  is  npni.  OpeninR  a  file  (ells  ProDOS  16  the 
name  nfihc  file  yriu  want  to  deal  with  and  permits  it  to  set  up  a  buffer  are-d.  it  needs 
to  manayc  llie  How  of  data  to  liiid  from  the  file.  To  open  a  file,  use  the  OPE\ 
command;  it  requires  the  fnllowiiiR  parameter  table: 


OPEN  (§10) 


injitit 

Symhalic 

or 

Offset 

Result 

Description 

+  0  tn  +1 

rcf_niiin 

H 

Reference  number  for  the  file 

+2  to  +5 

pathname 

I 

Po'inter  to  the  pathname  string; 

+6  to  +y 

uuILfield 

H 

Reserved  area  for  ProDOS  16 

The  only  p&ranieter  you  specilV  befure  railing  OPEN  is  the  pathname  pointer.  The 
parjjTietei'  OPEN  returns  is  ref.iium.  It  is  ai;  identifying  numhpr  for  the  open  file; 
this  nuinlMT  is  used  instead  of  a  pathname  by  all  other  ProDOS  16  commands 
dealing  with  open  Tdes,  You  nuist  store  ref.nuin  in  the  relerenLt-  nnniher  fields  of 
the  parameter  tables  lor  any  other  such  PmDOS  16  cominands  vi>u  will  call  before 
closinf^  the  file- 

ProDOS  16  sets  llie  mark  po.>ii(ion  to  0  when  you  open  3  file — ^the  start  of  the 
file.  Before  actually  readine  data  frnrii  the  file,  you  may  waul  tu  move  to  some  other 
position.  VitT  example,  if  the  Kle  w  TOmpo^ed  of  a  series  of  50-bvte  records  and  you 
want  to  move  directly  to  record  #3  (iiumbcrinj;  liegins  with  #f)K  you  would  move 
marlc  tn  position  150.  This  is  done  with  the  SKT.MARK  c-ommand;  its  parameter 
fable  looks  like  this: 
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SET.MARK  ($16) 


tnptit 
Symhoiic  or 
OJfset  iVamf  Result  DEsaription  

+  0^+1  ref_num  I  Reference  number  for  tlie  file 

+2  to  +5  pos[tion  I  The  ntw  mark  finsitinn 


The  ref_iium  in  the  SET.MARK  parameter  table  must  be  the  same  as  tlie  one 
returned  when  you  opened  the  Rte  whose  mark  position  is  being  changed. 

Anuther  matter  you  might  want  to  dcsi  with  before  reading  is  to  adjust  the 
newline  charattei.  This  the  charatter  that,  when  read  from  a  file,  will  leriniiiate 
a  read  opemtion  even  if  the  reijue^ted  number  nf  characters  has  not  been  read.  If 
yoii  asiigii  the  newline  (.'haraclier  tn  a  carriage  ^e^um  (ASCII  SODJ,  for  example,  you 
can  easily  rt^ad  a  te\t  file  line  by  line. 

Tlie  (.'timrnand  far  Metting  the  ncwline  character  is  NEWLINE.  Its  parameter 
tabli?  looks  like  tills; 


NEWLIN'E  |$n) 


Sijmbolic  or 
Offset  Name  Result  Description  

+0  to  +1  ref_num  I  Reference  number  for  the  file 

+2  to  +3  enable_!nask  1  Newbne  enable  mask 

+4  to  +5  newEine_€har  J  NewHiie  character 


A  character  read  from  an  open  file  is  logically  ANDed  with  the  value  of  enable_ 
mask  before  a  comparison  with  newline_diar  is  made.  If  the  end!-of-Iine  character 
jnighl  be  i  carriage  rrturu  who-*ir  high  bit  is  on  or  ofT,  use  an  enable_mask  of  S7F 
and  a  new|jnr;_char  of  SOD;  when  voii  do  so,  a  read  wdl  terminate  with  SOD  or 
$8D. 

Set  the  enable_ma.sk  tn  $00  to  chsablr  thf  nrwiine  feature. 
You  are  now  ready  tu  read  infiirmatiun  from  the  file  with  (he  READ  coinmaiid. 
The  parameter  table  looks  like  this: 
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READ  {U2.) 


input 

or 

Offset 

Natiie 

Desfriplion 

+  [)  tft  +1 

ref_num 

i 

Reference  number  For  file 

+  2  to  +5 

clata_  buffer 

1 

PoiiTitcr  In  atari  of  da,ta  bufler 

+  6  to  4-9 

requcst^cuunt 

1 

Number  of  bytes  to  read 

+ 10  tn  + 13 

transfer_cou]it 

R 

Number  of  bytes  actually 

read 


You  must  specift'  three  types  of  infumialion  in  the  parameter  list:  the  reference 
number  of  the  file  to  be  read,  the  starting  address  of  a  block  of  memory  where  the 
input  data  will  be  stored,  and  the  number  nf  hytes  to  be  read.  When  the  ciperalion 
ends,  the  transfer.cnunt  field  ccmtains  the  number  of  bytes  aqtually  read  from  the 
file.  This  number  will  be  less  than  the  requested  number  if  the  active  newline 
character  was  cnixiuntered  or  if  the  end  of  the  file  was  reached.  If  no  Lharact^^rs 
were  read  at  alL  the  awry  flag  is  set  and  the  atLUinulator  contains  an  t^rroi-  code  of 

S4C  (end-of-filc  eneouiitered). 

As  data  is  read  from  3  file,  the  mark  pointer  antomatically  advances,  so  there  is 
no  need  to  call  SET_MARK  explicitly  after  each  read 

When  you  are  all  through  with  a  file  you  should  formally  tlosc  it  with  the  CLOSE 
command.  This  frees  up  the  memory  spaces  that  PmDOS  16  allocates  to  Ihe  file 
when  it  is  first  opened.  The  parameter  lable  for  the  CLOSE  c^omioand  looks  like 
this: 


CLOSE  (SU) 


Inpul 
Sijmbotic  or 
Offset  Natne   Result  Description 


+0  to +1  ref_num  1  Reference  numher  for  the  file 


Once  a  file  is  closed,  you  canoot  read  from  it  again  until  it  has  been  reopened. 

If  the  ref_min5  specified  in  a  CLOSE  command  is  SOU.  all  files  at  or  above  the 
current  file  level  ar*.-  closed.  The  file  level  is  a  number  between  0  and  255  that  you 
can  set  nsing  the  SET.  LEVEL  command: 
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SET.LEVEL  [SJA) 


Input 

Symbolic  wr 
Offset  Name  Result  Description  

+0  to  + 1  level  I  The  new  file  level 


To  assign  a  t.-t;rtiiin  file  level  to  an  open  file,  use  SET_LEVEL  hefiirc  nprning  the 
file  with  OPEN.  You  eannut  dian^r  the  level  of  a  file  after  it  is  open. 

If  you  \viliit  to  determine  the  eurrent  file  level,  use  CjET_LEVEL.  Its  parameter 
table  is  the  same  as.  that  for  SET_LEVEL. 

You  will  not  need  to  Ixitlier  witli  file  levels  oftt-n.  Thi?y  hectinic  important  when 
you  want  to  manage  EXEC  files  properly,  EXEC  files  are  files  tti  which  the  openitinji 
system  looks  for  input  instead  of  the  keylxtarti.  If  you  switch  to  a  ki^her  file  level 
after  opening  an  EXEC  fiie.  subsequent  CLOSE  uperationiii  will  n<jt  elosc  the  EXEC] 
Rle. 

Tlie  subroutine  in  listing  lO-I  shows  how  to  use  many  of  the  ProDOS  16  cnm- 
niands  just  described.  Il  OpeiiS  a  (extfile.  disables  newline  mode,  determines  the 
file  size  with  CET_EOF,  uses  the  Memory  Manager  to  allocate  a  bluck  uf  that  size, 
reads  the  file  into  memory,  and  then  closes  the  file. 

Writing  to  a  Fili; 

The  prOeeilure  for  writinj;  to  a  file  [sec  listing  10-2}  is  .similar  to  the  one  for  reading 
from  A  file  lieiore  aL'tiidlly  writinii,  ynu  must  iipt'Ti  the  file  and.  if  necessarv,  position 
the  mark  pointer,  To  perform  the  write  operation,  use  the  WRITE  cninniaud;  its 
parameter  table  looks  like  this: 


WRITE  {S13! 


I  npit  t 

III' 

Offset 

Result 

Di-scriptian 

+0  to  +1 

ref_num 

1 

Reference  number  for  the  file 

+  2  to  +5 

tliLta_liuffer 

f 

Pointer  to  ^tart  of  data  buffer 

+  6  to  +9 

requpst_cniint 

I 

Nuiiilier  of  bytes  la  write 

+ 10  to  + 13 

transfer_ec>uiit 

H 

Number  of  bytes  actiiallv  written 
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The  tlata_l)uffcT  fi<>Id  [XjiiiLs  to  a  block  of  dala  you  wish  to  write  to  the  filp;  the  size 
□f  this  hkiLU  Ls  ijivfii  by  rei|uesl_Lr)uiil  The  lransffr_ti>iiul  fit-Id  reliirns  thv  iK'tiial 
number  (if  liytc!i  wrilteii  to  ihe  dis^c.  I(  will  bt-  It-sn  than  ih*-  requestfd  number  if 
thf  disk  becume  fidl  tkiriiiR  the  v.  r'n^  operatiijn  or  if  a  disk  error  cKcurrpd. 

One  LOmmiiii  fnriii  ol  writt'  (ipcration  is.  an  appi  nd.  This  is  the  prticr^s  of  e\- 
pandiiLfi  the  si?.i-  of  a  file  by  adding  data  to  it.  The  fgllt»wifig  subruutine  showi  how 
tn  append  data  to  an  fsistiiig  tile: 


_OPeN  OpenParma 

LDA  rtf_fmm 

STA  ref_numl 

STA  ref_num3 

_GE:T_e:DF  EOFParms 

_SET_P1flRK  EOFPerma 

_CLDSE  CtoseParma 

HTS 

flNDP 

r  ef  _r-urn 

DS  2 

DC  14'FileHampi 

DS  A 

EQFParmB 

flNDP 

r'ef  _niJmS 

DS  ? 

pOSl  t  1  QTI 

DS  -I 

Wr  i  teParms 

flNOP 

r  e-f  _Tiium2 

DS  2 

dd  ta_buf  f 

DC  l4'Buffer' 

request 

DC  I4'512' 

T  ransf  er 

DS  4 

CloaeParms 

fllSQP 

ref _num3 

DS  ^ 

f  i leName 

BTR  "MVFILE.DEnO- 

Buffer 

DS  512 

;  Op? n   th?  file 
;Get   referBTice  number 
;   and  store   it    m  other 
;  parame  t  e  r  lists. 

F 

;Gel   ttiE  file  51  le 
■.Set   ma rl    to   end    of  file 
-.Write  data  to  filt 
;Clo9e  thE  file 


iRaferFnc?  number 
jPoinler   to  pattirame 
;Handle   to    I/O  buffier 


; Pos  1 1 1  on  in  -fill 


[Buffer  containing  the  data 
jNumher  of  bytea   to  write 


;. Name  of  file 
iData    to  iivrite 


Tliis  example  uses  one  Luinniand  Hiat  has  not  tiei^n  discussed  yetr  GET^EOF,  GET_ 
EOF  returns  the  ^ize  ol  the  file,  in  liylesi.  in  a  four-byte  field  in  its  parameter  table. 
To  do  an  apjiend,  all  you  r^u^t  dt)  is  set  llie  mark  position  to  this  value  before 
writing  to  the  file,  as  shown  in  the  t-xamplc  rtbove. 
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The  iDompleCe  paramctL-r  table  I'ur  CET.EOF  UioU-^  like  this: 


CET.EOF  im) 


Offxet 


+  0  to  +1 
+2  to  +5 


Symbolic 
Name 


rel_niim 


Input 

or 

Ri'suU 


i 

R 


Reference  iiumbpr  ri>r  the  file 
The  end-ol'-filc  ptisition 


Two  other  coimnand^  you  iiihv  uav  in  ciinjuiKtioii  vfitli  utiU'  npt^rations  are  GET_ 
MARK  aiicl  SET.EOF,  Here  iire  their  parameter  lahles: 


CET.MARK  (S17) 


Offsel 


+0  to  +1 

+  2  to  +5 


SijiiihtiUc 
jVfljrie; 


refnLinl 
positiun 


Input 
or 


1 
H 


Description 


Reference  number  ior  the  file 
The  current  mark  position 


SET.EOF  {$18} 


Offset 


Symbolic 


+0  tci  + 1 
+2  to  +5 


ref_nuEn 
eof 


Input 
t'r 

Result 


Description 


Reference  number  for  the  file 
The  new  end-of-file  positirm 
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CET_MARK  retiimi:  the  current  value  of  the  mark  pointer  and  SET_EOF  sets  the 
size  t>f  the  lile  to  the  value  passed  in  its  parameter  tabic.  You  will  use  bnth  of  theni 
in  situations  in  which  you  want  tcj  ^^liminate  ever>thing  in  a  file  past  the  current 
ma,rk  position.  Here  is  the  subroutint'  to  use: 

_GET_J1flPK  MarkP^rmi  ;Get  current  mark  pti5itiori 

_SET_EDF  MarkParpn?  ;  and  make  it  the  new  file  511c. 

RTS 

SulK  an  operation  h  often  performed  in  word  processing  programs  when  a  file  is 
loaded  into  inemon,-.  incjcIiRed,  and  saved  tn  disk  under  the  same  name.  If  the 
modified  file  is  shorter  than  the  original,  and  yon  do  not  set  the  new  EOF  position 
after  the  write,  the  lile  wiJI  still  include  the  tail  rnd  of  the  uriginal  file, 

When  vou  v,Tite  data  to  a  file,  the  data  actually  is  not  ^aved  tn  disk  ri^ht  away. 
Instead,  it  is  ijlaccd  in  a  ProDOS  I/O  bulW  that  is  translerred  to  disk  only  when  it 
fills  Lip  or  when  (he  file  closed.  You  can  fort-c  ProDOS  to  empty  the  I/O  buffer 
at  any  time  using  the  FLL'SH  command: 


FLUSH  (S15) 


Input 
Sifnibolic  or 
OffsL-t   Name  Result  Description  

+0  to  +1  ref.tmm  I  Reference  number  for  the  file 


Ciillinp  FLUSH  niininuzes  the  risk  of  losing  data  if  the  system  crashes  or  the  power 
goes  oB  betnre  the  file  you  are  writing  to  is  elnsrd.  It  does  slow  down  the  effective 
execution  speed  of  a  program,  however,  so  it  is  not  used  often, 
Note  that  ifref.nmn  is  StXJ.  all  open  files  are  flu.shed. 

DEVICE-MANAGEMENT  COMMANDS 

The  device- management  commands  :ire  for  de^aling  with  block  devices  themselves, 
not  iKe  individual  files  they  cnntajn.  They  perform  such  chores  lowdevel  block 
I/O  and  disk  fbrmatfiiig. 
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Formatting 

Disks  must  be  formatted  with  the  FORMAT  coimmaiid  before  you  can  save  files  to 
ihem.  Formatting  is  actually  a  two-step  process; 

1.  Cnnditiiiniiig  the  magnftic  Mirfiicc  of  the  di^V 

2.  Writing  boot  code,  directory',  and  block  usage  information  on  the  disk  in  the 
manner  dictated  by  the  operating  system 

Because  formatting  pertnanently  erases  any  information  on  a  disk,  you  Sihould  ask 
the  user  to  verify  such  an  operation  if  the  disk  is  not  blank- 

The  structure  of  the  piiramcter  tabic  for  FORMAT  is  as  follows: 


FORMAT  ($24) 


Input 

Symbolic  or 
Offset  Name  Bemlt  Description  

+0  to  +3         dev_name  I  Pointer  to  the  device  name  string 

+4  to  +7  voI_name  I  Pointer  to  the  volume  n^inie 

string 

+S  to  +S  file_sys_id  I  Operating  system  ID  code 


The  dev_name  parameter  is  a  pointer  tti  the*  dqvice  name  string  (the  string  will  he 
.Dl,  .D2,  and  sir  OiiK  The  volume  name  ^triIlg  can  be  up  to  16  characters  long;  it 
must  adhprp  tn  the  ProDOS  file-naming  rules  and  must  include  s  leadinj^  slash  [/). 

The  meaning  of  the  file_sys_id  field  was  explained  earlier  in  connection  with  the 
VOLUME  tcjmniand  It  describes  the  operating  system  used  by  the  conmiand.  hi 
this  case,  it  tells  FORMAT  the  technique  to  use  to  lay  out  the  disk  directory 
information  on  the  volume. 

Keep  in  mind  that  early  versions  of  ProDOS  16  supported  the  formatting  of 
ProDOS  disks  unly  (file_sys_id  -  $01).  You  will  get  an  error  code  of  $5D  (operating 
system  not  supported)  if  yuu  iet  file_5ys_id  to  anything  other  than  $0L. 
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Accessing  Specific  Blucks 


If  you  are  writing  ii  utility  program  inch  as  a  dislc  copier  or  a  file  undeleter.  yau 
will  probably  want  to  rtild  and  write  specific  blocks  on  a  disk.  To  do  tliis,  use  the 
READ.BLOCK  and  WRlTE_BLOCK  eommands.  They  both  use  the  same  type  of 
parameter  block: 


READ.BLOCK  ($22) 


Offset 


+0  to  +1 

+  2  to  +5 
+  6  to  +9 


Symbolic 
Name 


dev^num 
data  .buffer 
block  niim 


Input 
or 

Result 


Description 


Device  reference  number 
Pointer  to  the  read  buffer 
Block  number  to  read  in 


WRITE.BLOCK  ($23) 


Offset 


+0  to  +1 
+2  to  +5 
+6  to  +B 


Si/mholic 
Name 


dev_mim 
data.buffer 
block  nuni 


Input 
or 

Result 


Description 


Device  reference  number 

Fainter  to  write  buffer 

Block  number  to  be  written  to 


The  memory  blocks  piiinted  to  by  data.buffer  in  each  case  are  exactly  Sl2  bytes 
long  (the  size  of  disk  block].  The  block  numher^  on  a  disk  range  from  0  to  an 
upper  liniil  that  depends  on  the  nature  of  the  disk  device-  Use  the  VOLUME 
commjmd  to  determine  the  size  of  a  disk  volume  in  bloc  ks. 

The  dev_num  parameter  ]ieedcd  by  both  READ_BL0CK  and  WRlTE_BLOCK 
is  a  deWce  reference  ruiinber  [.Dl,  .D2,  and  so  on],  not  the  device  name.  To 
determine  the  t-cference  number  for  a  given  device  name,  use  the  GET_DEV_ 
rJUM  command;  its  parameter  table  ib  as  follows: 
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CET_I>EV_NLiiVJ  (S20) 


Input 

Symbolic 

nr 

Offset 

Reswlt 

Descriptiffn 

+0  to  +3 

I 

Pointer  to  the  device  najne  string 

+4  ta  +5 

d  I' Valium 

R 

Device  rcfprcnce  numlier 

Wli&n  ProDOS  first  starts  up,  it  scans  the  system  for  hlotk  devices  and  assigns  them 
unique  device  referent*  numbers.  These  numbers  are  consetutivK  integers  begin- 
ning with  1.  This  identifi  till  ion  system  is  quite  difierent  from  lliat  vised  in  ProDOS 
S  in  wliich  cleViHL'es  art"  identified  by  slot/drive  tombinatiojus- 

Last  Device  Act-esscd 

Pri>DOS  16  has  d  command  ibr  determiniiie;  the  reference  number  of  the  hst  device 
at:cesscd  by  a  read  or  write  uoinmand,  This  is  the  CET_LAST_DEV  L-ommand: 

GET_LAST_DEV  ($21) 


Input 

Symhohc  or 
Offsnt  Name  Result  Description  

+  Oto+1  dev^num  R  Device  reference  number 

If  GET_LAST_DE\'  is  unal>Ie  tu  dctfTniine  what  the  last  device  was,  il  returns  an 
error  code  of  SfiO, 

OPEHATJNG  ENVIRONMENT  COMMANDS 

Voii  can  use  the  operalinfi  emironmenl  commands  to  detemiine  tlic  name  of  the 
currendy  rLninm^  apphcatlon,  the  name  of  the  bunt  voliLnie,  and  the  ProDOS  16 
verMoji  nuniljer,  These  commands  aho  include  the  iniporlant  QUIT  tomniaiid, 
which  you  will  usr  to  transfer  ciintrfil  from  one  application  lo  auother. 

Status  Conmnundfi 

It  is  often  LTJiivenicnt  for  a  prORram  to  know  its  own  name.  It  ma>  need  to  know 
this  infnrmatioiL  su  it  ean  transfer  a  cnpy  nf  itself  to  a  RAW  disk,  for  example.  Instead 
of  using  a  specific  name,  >  nu  .should  use  the  CET_\.\ME  ctuninand,  just  in  case 
the  user  has  reclamed  the  program, 
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Thf  paratiicter  table  for  CET_NAME  lonka  like  this; 
GET.NAME  ($27} 


I  til  Hit 
Symbfhc  or 
0£f^t'l   iVhjiu?  ResuU  Descripthm 


+  0  to  +3  daEa_l]uffer  R  Pntnter  to  applitritinn  name  strinj; 


The  space  for  the  name  should  he  lH  hytrs  long  sn  tliat  there  wWl  he  room  fiir  the 
lonjjest  possible  rileriaiiif  and  the  isretdhnK  len((th  byte. 

Ni>tiec  tliiit  CET_\AM£  returns  thf  filename  only,  Thf  subdiretjtniT.'  in  which 
it  resides  is  given  by  the  1/  i^refix,  L'.se  t^ET^PHEFIX  to  determine  what  this  prctfix 
in. 

To  access  files  on  tlie  bnot  diiik.  y^ii  ciin  sprtify  a  pathname  eonslriieted  In  adding 
the  "*/"  prefix  dei^igiiator  to  a  partial  |jathiiarnc  If  >'r)ii  (iced  to  kiiuw  the  actual 
n^ne  of  the  btKit  disk,  use  the  GET_tiCX>T_\"()(.  coniinand,  Here  is  its  parameter 
table: 


C ;  RT  _  BO  O  r_\'  O  L    ( §28) 


Sijinhoiic  <n 
Offset  Name  Resuil  Description 


+  0  to  +3  data_huffer  R  Pointer  to  the  volume  name  string 


CFT.BOOT.N'Ol,  return"*  a  iiuuie  wliiLh  he^ins  and  ends  with  a  slash.  the 
datajiuller  spate  diiinkl  t>e  IS  bytesi  luiij;, 

There  is  also  a  CET_VF;RS]0\  eunimaiid  Fnr  de|<-rmiuiiiR  the  versi(jn  number 
uf  ProDOS.  \n  applicatinn  should  thL-elv  the  \  eisii»n  number  li  the  pruKraiu  works 
only  will]  eertiihi  versions  of  ProDOS.  Here  is  ihe  parameteT  tiilile: 
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GET_\TRS10\  (S2A 


liiftu! 
Symbolic  or 
Offset  Name  Result   Description  

+0  t(i  + 1  version  R  ProDOS  16  version  numher 

The  Inw-nrder  byte  of  bhf  version  word  represfnts  the  minor  release  numbtr  and 
the  high-order  byte  repr«-s(^iits  Hie  major  rL^ltast-  vfrsitiii.  Version  2.1,  fur  example, 
would  be  stored  as  $0201.  If  rhc  high-order  bit  of  the  result  is  1,  it  is  a  prototype 
version. 

The  QUIT  Command 

ProDOS  16  has  a  siii^ln  coniTiiand  you  can  use  to  leave  One  application  and  transfer 
control  to  another:  OL'IT,  With  it  yon  ran  eilher  run  a  spcT-iRc  propnun  or  return 
control  to  the  program  whuit  UstrlD  is  on  the  top  of  a  (^uir  Brtnni  StaL-k, 

The  Quit  Bf^turn  Stack  is  where  an  application  places  its  UserlD  if  it  wishes  lo 
regain  mntrol  the  next  lime  an  appliLdtitin  qnttji  u-ithoul  specifvin^  the  palhiiame 
of  the  next  application  to  run.  Tiie  avaiJaliility  yf  a  Quit  Ketum  Stack  inakos  it  easy 
for  a  supervisory  program  to  execute  suhsidiiiry  programs  so  that  control  always 
eventually  returns  lo  the  original  pruf-rain.  In  fact,  the  CIS  program  launcher  always 
pushes  lis  UscrlD  im  the  Quit  Heturn  Stack  before  lauocliiitj^  an  application.  If  it 
did  not,  you  would  mi.  return  to  it  when  an  appJication  endeJ. 

Use  the  following  parameter  table  with  the  Quit  command: 

QUIT  ($29)   

Input 

Symbolic  or 
Offset  Name  Result  Deicriptivn 

+0  to  +3  pathname  ]  Pointer  to  next  pathname 

+4  to  4-5  flags  I  Reluni/Restart  flags 

The  pathname  parameter  points  to  the  pathname  of  a  ProDOS  16  or  FroDOS  H 
sy.slein  projiram.  As  usual,  the  jialbname  liesin,s  with  a  len^ith  byte.  The  current 
application  will  load  and  run  tbi:i  program  when  you  cal!  the  QUIT  command. 
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If  the  pathname  pointer  is  0,  and  the  Quit  Return  Stack  is  nut  empty,  ProDCJS 
16  pulls  a  L'jii-rlD  irnuni  the  Quit  Return  Stat'k  anil  e.xt'Lutes  the  program  with  that 
[D.  It  the  Quit  Return  Stack  is  empt^".  PrtiDOS  16  ealK  up  a  ^tanilarJ  tli.spatfher 
scbr{}utine  that  lets  you  t^'pc  in  the  name  of  the  next  system  program  tn  run.  reboot 
the  disli,  or  cun  the  SYSTEN3/STAHT  proerani. 

Only  the  twa  hi^h-ordfr  bits  uf  tl]t  Ba^i  paramettr  are  sipiifieant.  If  bit  15  is  1, 
FroDOS  places  the  cturent  opp I ica lion's  UserlD  oil  the  Quit  Keluni  Stack  belbrt 
parsing  control  to  the  apjDlication  described  by  the  pathname  pointer.  Tliis  meanji 
that  control  eventually  will  return  to  the  current  application  as  later  programs  cjuit 
with  A  0  pathniitne  parameter.  II'  bit  IS  is  0,  nothing  is  placed  cm  the  Quit  Return 
Stack 

If  bit  N  of  the  flags  is  1,  the  calling  program  is  capable  of  being  restarted  ".vjthout 
being  reloaded  from  disk.  If  control  returns  to  it,  it  will  not  he  loaded  from  disk 
unleis  it  has  been  pur^;ed  from  niemor\'  by  the  Menion.'  Manager. 

l*he  QL'IT  cimimaiid  never  returns  ewntrol  tt>  the  appheaticm.  If  an  errtir  tx:eurs, 
an  interactive  di;ilo^  hox  dppe^s  on  the  serpen  with  the  error  number  on  the  last 
liii*f  in  the  box. 

LNTERRUPT-CONTKOL  COMMANDS 

ProDO.S  16  has  a  16-enlry  ititenial  table  tliat  contains  the  addresses  of  the  subrou- 
tines it  calls  when  it  receives  word  diat  a  6.5Slfi  IHQ  Interrript  signal  has  occurred. 
It  ca]h  eatb  subroutine  in  sequence  until  one  of  tbeni  claims  (he  interrupt  (by 
clearing  the  carry  flagl.  If  the  interrupt  is  not  claimed,  a  filial  system  error  occurs. 

To  use  an  intcmiptiiig  device  with  ProDOS  It),  lie-in  by  loading  it*  interrupt- 
handling!  .^uhroutinf  into  memory.  Tbc  characteristics  of  sucb  a  subroutine  are  as 
follows^ 

It  must  be  able  to  determine  if  the  sourt-e  of  the  interrupt  is  die  device  for 
which  it  iFi  de^i};ned. 

If  its  device  not  the  si>un.-e  nf  the  interrupt,  it  niust  .set  the  carry  Hag  with 
SECL 

If  its  device  is  the  wiiirLX'  of  the  interrupt,  it  must  handle  the  interrupt  by 
eleariog  the  interrupt  condition  (usually  by  reading  the  device  status],  perform- 
ing the  necessary  I/O  operation,  and  then  clearitig  the  carry  flag  with  CLC 

It  must  end  with  an  KTL  instructioti. 

The  internipl  handler  does  not  have  to  preserve  the  status  of  the  A,  X,  or  Y  registers 
since  ProDtXS  restores  Jnd  saves  tlicin- 

Next,  install  the  interrupt  handler  with  the  ALUX]_INTERRUPT  command. 
TJie  last  step  is  to  enable  interrupts  from  the  external  device. 

Here  is  Che  strutture  of  the  ALLOC  .INTERRUPT  parajiietcr  table: 
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ALLOC_INTEBRUPl-  (S31) 


Input 
Sytrihodc  or 

Offset  Name  Remk  Descnptinn  

+0  to  +1  !nt_nuiTi  H  Interrupt  handler  reference  number 

+2  to  +5  iiit_L-ii(]c  I  Pointer  to  interrupt  handler 

In  this  table,  int_num  is  the  reference  numhcr  returned  liy  ALLOC.INTERRUPT. 
Int_cnde  is  a  pointtT  tn  the  start  of  the  tixle  for  the  interrupl  handler. 

Note  that  ifthe  interni[it  fiandlcr  uses  system  resources  that  may  be  husv  {usually 
ProDOS  Ifi  ilself),  it  should  first  check  [he  Scheduler's  busy  flag  at  .SEi(X]FF,  If 
this  flag  is  iioji-zero,  iLandUiif^  of  the  interrupt  muat  be  deferred  by  adding  a  task  to 
the  Scheduler's  queue  wsth  the  SchAddTask  function: 


FHfl  ;  «pa<:«    for  result 

PushPtr  TheHandief  ;S«ibroullne  for  Scheduler   to  call 

PLA  ipop  Bciaiean 


The  BiHilcan  result  is  true  if  the  task  was  added  tu  the  queue. 

HardlcEnt  llie  address  nf  a  suhruuliiie  [ending  in  RTL)  inside  the  interrupt 
handler  that  includes  the  eall  to  the  system  resuuree.  When  ihe  busy  fla^  is  turned 
o£f  by  the  interrupted  program,  the  Scheduler  automaticaUy  calls  the  Handleint 
subroutine  to  coniplele  processing  t>f  the  iiiternipt.  (If  \im  doti't  check  ihe  buiv  flag 
and  ProDOS  is  liusy,  yuu  will  ^et  an  error  code  of  $07  when  you  attempt  tu  use  a 
ProDOS  cummand- ) 

To  renuivc  an  entr>^  from  the  intemjpl  hwndler  table,  use  DEALLOC^INTEH- 
RUPT,  but  onlv  after  voii  have  UAd  thv  external  dtviL-e  to  stop  generating  interrupts, 
DEALLOCJNTEHRUFT  uses  this  parameter  table: 


DEALLOC.INTERRUPT  ($32) 


Sf/mholic  tT 
Offset  A'gjng  Reault  Desc  rip  f  io  n 


+C  to  +1  int_num  I  Interrupt  handler  reference  number 


The  int_nuni  you  pass  to  DEALLOC.INTERRUFT  is  the  number  returned  by 
ALLOC.INTERRUPTwhen  you  mstalled  the  handler. 


iTiterrupt-control  Commands  361 


STANDARD  FILE  OPERATIONS 

Twn  fi  If -related  operations  are  CDiiiniori  lhat  Applt  Coininiter.  llic  has  develnpfd 
an  rtitirf  tcx»]  st-t  to  support  them,  The  first  npcfiition  is  for  dispkying  a  list  nl  tliak 
RIcs  -in  thiit  one  can  br  ua.'iily  Spt^lt-Lled-  Tlic*  stcuntl  une  is  for  regurstinn  the  iimne 
for  a  file  that  is  to  be  saved  to  disk. 

The  Funttiuns  used  to  perfiirm  these  operatinns  form  part  of  the  Standard  File 
Operations  tool  set  {Imyl  set  23).  These  I'unctitins  are  called  in  the  same  way  iih  nny 
other  tool  set  function.  They  are  not  ProDOS  16  eoniniands,  so  do  nut  call  (hem 
witl]  the  ,st,iin.dard  ProDOS  16  tailing  scqiienc:e. 

The  Standard  Fill-  Operations  sUirt-up  function  is  SFStartup.  Call  it  tmce  at  the 
bef^itining  of  a  prngrain  that  uses  the  tool  set; 

PushWord  MylD  ;  ID   of  prpgram 

PushWord  DPAddr  jfiddrEsa  of   one  page   j n  bank  JOO 

_5FE la  r  tup 

As  y<iu  can  see,  SFStiirtup  re([uires  a  direct  pa^f  in  bank  ^(K)  to  worl;  with. 

Tht:  slmt-down  fiinLtiitn  ii  SFShulDown.  It  requires  no  input  pavamettrs  and 
does  not  return  results. 

SFGetFile 

The  filf-seleLtion  i'unetion,  SFC^etFde,  was  used  in  the  proKrain  in  listing  10-1.  It 
creates  a  dialog  Ixis  siiniliir  to  the  one  shown  in  figure  HJ-2.  At  the  top  of  the  left 
half  of  this  box  is  the  iiainp  of  tht'  eurreiil  cliirttory;  below  tliis  iiianie  is  a  window 
contLiiiiinR  ^n  alphabetical  list  (if  files  in  ihiit  directury,  eaeb  preceded  by  an  icon 
indicatinj;  the  gf-ncral  file  type,  Tlie  window  ha.s  a  vertic-al  stroll  bar  that  tan  be 
used  to  move  any  imrtion  of  the  lisl  nf  ftli  s  into  view  On  the  right  side  are  liiur 
liulto[is  labelc'd  Opeo.  Close,  Ciiiiicl.  and  Disk. 

Vou  can  .select  a  tile  l>y  liiphlighting  its  name  [by  L-lickins  on  it)  and  then  eliekinp 
the  Open  boltnn,  "r  simply  hy  dnublr-clickinj;  tm  its  name.  Yon  can  also  hijilllifiht 
a  niiiiie  by  typine  thf  first  chanicter  of  the  name;  if  there  is  more  than  one  name 
beRiniiing  with  the  character,  ihf  first  one  ib  hiilldijihted  Th*7  np-  and  down-arrow 
keys  can  be  ii.sed  to  move  ihnmph  the  list  of  files  ojie  ontry  at  a  timt^. 

If  the  selected  file  is  a  snbdircttnry  (marked  by  a  fik'-foldcr  icon),  the  luune  of 
the  torrent  tlirecton  cluinjics  and  a  list  of  the  files  in  the  new,  lower-level  sub- 
director)'  ^bown-  If  the  file  is  not  a  subdirectory,  the  dialog  box  disappears  from 
the  screen  and  llie  program  tiin  deal  with  the  selected  file 

[|  is  alsfi  poshible  In  display  aod  .seleet  files  in  higher-level  subdirectories  or  on 
other  disks.  To  move  to  lhe  nr  st  hi^;he^  subdirectory  (tlnser  to  the  volume  director;') 
click  once  un  the  preinx  name  shown  above  the  file  window,  type  the  Esc  key.  or 
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Figure  lU-2.     Tin-  SPCi-tFik-  niiilnj:  Bns 


Belectafiletouiew: 
^  /flpw/W/ 

D  Kl&.Sound 
D  H16.Stdfile 
D  MlUexttool 

□  Hiytility 

□  M16.UindDV4 
DHg 

D  Ma.Hoc5 
D  Standard .flsiR 

%'iVp'' 

t     Disk  ] 

(t     Open  3) 
[    Close  ) 

r    Cancel  1 

flick  tht'  Close  butti^n,  Siil>se()ueiit  clkks  will  t-vientually  take  ynii  riftht  up  to  the 
vdIijiik'  ilircttiiry.  To  display  llit-  fi!i-s  ini  iiiiotlitT  disk,  dit'k  the  Disk  hiitton  until  a 
list  (j|  flic  disk's  fdts  iippt-ars  in  ihf  lile  *i'iiidou'. 

Xiitict-  that  the  first  time  ynu  click  llie  Disk  butlon,  the  disk  in  the  current  drive 
is  exaiuinct!  to  src  if  ynu  have  removed  it  ;iiid  instated  aiuillitT  tlisk;  il  yuu  Uaxp 
inserted  n  new  clist;,  the  files  on  if  urc  shmvn,  II  ynu  nul,  tht?  filt-s  on  the  dit,k 

m  llie  uexl  drive  ire  shnwn.  Suhsf(|ii<'nt  clicks  will  briiin  yoii  lo  the  otht?r  drives  in 
tile  system. 

SPCetFik'  rfqiiirc'^  six  input  parameters,  includiiin  a  pi.jiiiler  tc  a  pcira[nt;t.er  hst 
called  a  reply  record.  When  SFt^flFilc  ends,  the  reply  record  can  Ijc  read  to 
determine  which  file,  if  anv.  \\^  >;i-leict<'d.  Here     how  tu  fall  SFGetFile: 


PustiUford 
Pj  shiUfor  d 
PuitiPtr 
PustiPtr 
PuahPtr 
PushiPtr 
_SFGetFi Je 
RTS 


NhereX  ;  H  or  i  ?q  rit  a  I,   ptsiition  of  hat 

UhereY  ;Vertical   po^itior  of  box 

P  t°  Dirp  t  jPainter    Id  prompt  string 

FiilerProc  iPointer    lt>  filler  procedure 

TypeLlst  jPointer    to   file    type  list 

Re-plySec  ;Pointer    to  reply  record 
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D5 

2 

Fi letype 

DS 

2 

DS 

2 

F  I  leriame 

DS 

\& 

PalhriBme 

DS 

1  25 

;Staridard    repiy  record 

jTrue  =  open      False  =  cancel 

;Fiie  type  code 

;flLixlliary  type  code 

; Fi I e  name  string 

;Fli11   pathname  string 


TypeList  DC 
DC 
DC 


ITS' 

n ' *B0 ' 


; t by^ e  h   "ot  word | 
iText  file 
; Source  file 


Prompt        STR  'Select   a  file:'    ;PrcmptLng  string, 

THl-  first  two  parameltTS  reprt'senl  llie  ^iDordiniilt'  iit  thf  tup  lel't-hanti  t'nm*?T  iif  the 
dialog  h[jx.  Tlw  Prtimpt  string  is  displayed  iiisidt  tlic  hoy.,  just  abuve  tiie^  Riff;  window, 
and  is  Mii()]}i(SL'd  to      a  short  incssa^se  to  die  user. 


Kilter  PriM-'ediirt' 

FilterPruf  is  ;i  siihrniitinc  that  SFCrtFilc  calls  to  determine  how  to  display  the 
name  uf'a  file  or  wh£?th(-'i"  hi  dispky  it  at  all  FilterProc  returns  one  of  three  result 
codes,  which  SFCetFile  examines  to  make  the  determination: 


0  D(i  not  display  thf.  Bleiiamp 

1  Display  tht"  filcmnnc  In  dimmed  text 

2  Display  the  filename  in  standard  text 


Filenames  which  appear  in  dimmed  text  in  an  SFGetFile  dialog  box  cannot  be 
selected  by  the  user. 

II  the  pointer  ti>  FiltcrPnie  is  0.  SFGetFile  does  not  call  a  Biter  procedure,  and 
all  filenames  are  displaytrd  and  selectable, 

SFGetFile  tails  the  filter  procedure  in  much  the  same  way  an  application  calls  a 
tool  set  funt'tinn;  it  first  pushes  space  for  the  result  code  (a  word)  on  the  stack,  and 
then  puslies  a  pointer  tct  the  file's  39-byte  director)'  entr>';  filially,  it  calls  tlie  filter 
procedure  with  a  JSL  instructioTi. 

A  filter  prixredure,  which  y<iu  must  writr  yniirself,  shanld  first  decide  bow  the 
filename  is  to  be  displayed.  The  decision  is  ii.siially  based  on  the  value  of  the  file 
type  code  or  the  filename,  hoch  of  which  are  stored  in  the  directory  entry  record 
whose  address  is  passed  as  a  parameter  The  structure  of  a  directory  entry  record 
Ls  shown  ill  table  10-4. 

After  deciding  bow  to  display  the  filename,  the  filter  priwedure  must  place  the 
appropriate  result  code  in  the  space  reserved  fur  the  result  on  the  stack.  The  address 
nf  thsN  space  will  be  tlie  value  ot  the  stack  pointer  plus  S  it  the  stack  pointer  has  not 
changed  since  the  proc^edure  was  entered. 
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Tsbk'  10-4:     The  Format  (ifa  ProDOS  Directdry  Enti^ 


Offset 

+0  (lim  kfUT  biis) 

Length  of  filename 

+  0  (hij;h  four  bits) 

Storage  type  code 

+  1  to  +15 

Fildmint  churiiL'tt^r  litring 

+  16 

File  type  code 

+  17  to  +18 

Bltick  number  of  file's  index  block 

+  19  to  +20 

File  size  [in  blocks) 

+  21  to  +23 

EOF  pQiiitiDii 

+  24  In  +25 

Creation  date 

+26  to  +27 

Creation  time 

+SS 

Version  of  ProDOS  which  created  the  file 

+29 

Lowest  version  of  ProDOS  that  ean  Uise  file 

+30 

Access  code 

+31  to  +32 

Auxiliary  type  code 

+33  to  +34 

Mndificiitiun  date 

+35  to  +36 

Modification  time 

+37  to  +38 

Block  number  of  first  subdirectory'  block 

Finally,  the  procedure  must  remove  the  input  parameter  from  the  stack  by  moving 
ihe  three-byte  retnrn  address  on  the  tt>p  i>f  the  staLk  up  by  four  bytes  and  adding 
4  to  the  stack  pointer.  When  th*"  prncednre  end?,  with  HTL,  the  result  is  On  the  top 
of  the  staeit.  readv  to  he  pnpped  offhv  KFGetFile. 

Here  is  an  example  of  ;i  filter  proeediire  you  could  use  Id  prevent  files  with  a  file 
type  code  of  SFF  (ProDOS  H  aysterii  programs)  from  being  displayed: 

PHD  ; Save  current  d.p. 

TSC  iStackpDintertciaccumuldtDr 

TCD  ;AligTi  d.p.   with  stack 

LDV  #15  ;0ff5cl   to  file  type  code 

LVf\   [t&],Y  jAccesa   the  file   type  cede 

flHD   #Si)OFF  llsol^tP    the  byte 

CMP  #tFF  iProDOS  3  ayatem  program? 

BNE    StftCode  (He,    ao  brarch 
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LDfl  *D 


■,  0    =  cJon  '  t    1  TIC  1  tide 


SetCode     LDfl  #? 


'.Z  -  include/selectable 


iRestore  direct  pagt 
; 5av!:  the  result 


LDA  2fS 
STA  S.S 
LDA  1  .S 
STA  5,S 


;  Move  the  3-hyle  return 
;  aijdress  up  by  A  bytea. 
jCit's   now  at   SP+1    to  5P+3; 


T5C 
CLC 

ADC  ftA 

TCS 

BTL 


jfldd  A  to  I he  stack  po Inter 


; (Dnni t   use  BT5 ! ) 


This  procedure  illustrates  the  standard  technique  tor  deillin^^  with  poinhTS  thai  are 
piLsscd  on  ihe  statk.  pushing  \hc  current  i  tlKie  ol  ihe  dircLt  page  register,  this 

routine  defines  a  new  direct  page  that  is  ahgjied  with  the  top  of  the  5*aek.  Tliis 
mean^i  t^ic  pointer  to  the  direeturv-  entr>-  1s  at  imsilioti  $06  in  the  tlirett  pa^e  (ahove 
the  twn  hytcs  pushed  by  FllD  .ind  the  three  bytes  pushed  by  the  initial  JSL  to  the 
prueedurf  ];  because  the  pahiier  is  now  in  direct  page,  you  can  access  the  elements 
of  the  directory  entrj'  with  the  long  indexed  indirect  addressinji  mode. 

There  are  two  other  important  mattL'rs  related  to  the  use  of  ^  filter  pRjeedure, 
First,  you  wil]  not  be  able  to  interfere  with  the  display  of  a  subdireclort'  file;  such 
files  are  al>v"dy.s  shown  and  are  selectable,  Second,  SFCptFile  allows  a  filter  prute- 
dure  to  chanjje  the  TOntcnts  of  the  A,  X,  and  Y  registers  but  ncit  the  direct  pa^e  or 
data  bank  re^iiters.  if  you  must  ehange  the  direct  page  (as  in  the  afjove  example) 
or  the  data  bank,  save  it  on  the  stack  flfsl  and  restore  it  just  hefore  the  procedure 
ends. 


Type  List 

TypeList  is  a  table  cuntiiining  a  list  of  file  type  i^odes,  preceded  by  a  coutll  byte: 
each  file  type  cixle  ucLupiei  one  byte  in  the  table,  li  the  filter  procedure  pointer  is 
U,  SFGetFile  displays  the  name  ofa  file  only  if  the  file'ii  type  code  is  in  this  list.  If 
a  filtcT  procedure  is  defined,  filenanjes  referred  to  in  the  type  list  are  passed  to  it 
for  further  analysis. 

For  example,  if  you  want  to  display  only  files  containing  readable  test,  use  the 
followinj;  TypeList  table: 

TypeList     DC   n'2'  ;  Two  ■entries 

DC  H'O-?'  jTextfile  (TXT) 

DC  H'BO'  ;flPW  source  file  (SRC) 
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Directory  files  arc  liWvs  displavf  rf,  even  if  thcv  arc-  not  i-splkith  mcliidec!  in  the 
Typt-List  tahle. 

If  the  pointer  to  a  TypeUst  tabJe  h  0.  all  types  »f  files  will  be  dkplaved  unless 
sotnc  are  n-slrlL  ttd  by  ii  RltiT  proi.'t;dtire, 

Ytm  sKould  use  d  TypeLLst  whont- vt-r  tlie  \ist  nf  file  hix-  codes  voti  want  to  permit 
IS  relatively  Ahnrt.  If  you  are  trying  tci  preyent  the  display  uf  only  a  lew  types  of 
file?,  it  is  more  cniivenicnt  to  use  a  filter  proeeilure  instead  ol  Typtlist.  You  will 
also  want  to  use  a  lilier  pn.eed.ij-!'  if  vno  wish  tn  allow  restrieted  file  names  to  be 
displayed,  but  not  seleetable.  The  filttr  proi:edurc  in  listing  lO-l,  is  an  example  of 
-such  a  filter- 

K&ply  Record 

WWn  the  user  dicks  the  Open  or  Cancel  button  in  the  dialog  box,  control  retorns 
to  the  applleatioii  and  the  resvilts  are  in  the  reply  record.  The  first  field.  Good,  is  a 
Boolean  value  iudicafiiiii  which  hottnn  w&a  pressed;  ii  is  true  (non  zero}  if  it  was 
Open  or  lalsc  (zenjI  if  it  wds  CaiieeL 

Tbe  remaining;  fiekli  have  meaning  only  if  Good  is  true.  Filetype  and  Aojttype 
hold  the  file  type  eude  and  the  auxiliar>'  type  eode  of  the  selected  file,  respeettvely 
The  ]ianie  of  the  file  is  stored  ,it  Kileziame  and  die  (oil  pathname  ol  the  file  stored 
at  Pathname.  In  each  ease,  tbe  name  .striiiR  is.  preteded  bv  a  icoEth  byte. 

if  Open  i.  pressed.  SFCetFile  Sets  prefix  0/  tHie  tlefanll  di^eeto^^■)  to  the  cIireetor>' 
111  which  the  selected  file  resides.  PrefiN  U/  docs  not  chailfie  if  Ca^ieel  is  pressed- 

SFPutFile 

The  foiK-tiQii  tfi  nse  when  you  «aiit  to  request  that  a  filename  be  entered  is 
SFPutFile  [see  listioK  UI-2)-  Thi^  l\iiic(i.)n  generates  a  dialog  UiK  similar  to  the  one 
shown  in  figure  10-3.  Uke  a  SFCIetFile  Iwx.  this  dialog  box  contains  a  divectory 
windnw  r>n  tlie  left  side_  but  all  T,.,n-diree£or>  filps  are  dimmed.  What  you  are 
suyposed  to  do  is  move  to  (he  correct  subdirectory  ol  (he  correct  dislc  iisinf;  the 
Open,  Close,  and  llisli  huttons  imiith  as  you  would  if  von  wore  using  SFtic  tFile! 
Next,  you  type  in  the  name  of  [he  file  to  hv  saved  in  the  text-entr^  rcctan^!le  in  the 
lower  left  ennicr  of  the  hox.  Tlii^  is  an  EditLine  dialog  item,  so  \oo  can  LSe  all  the 
standard  editing  techniques  to  enter  a  name,  VVh*'n  the  SFPutp-ile  dialuj;  first 
appears,  a  dpfnult  filename  is  hifihlit;hted. 

II  is  also  pnssihle  to  create  a  new-  subdirectory  before  selecting  i  filename.  To  do 
this.  t>pe  in  a  subdirectory-  niinie  and  then  elick  the  New  Folder  button. 

Here  is  how  to  call  SFPufFile: 

Pu^hWprd  Where>r  ;HoMiOTilal  position  of  box 

PushWcrd  WhercV  ;Vertical    po5it,c.^  of  bo). 

PushPtr     Prompt  iPoinler    Id  proffipl  siring 

PuBt^Ptr     DngNflmt  ^Pointer   to  default  filename 
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FiRure  10-,X    The  SFPutFilf-  Dialog  Box 


Free:  106k  out  of  li324k.  ^ — ^ — ^ 

CDPp 
CpSjjsteni 

CD  Utilities 

u|  I  New  Folder  ] 

0 

(     Oj)(Mi  ) 

Enter  a  name  for  the  file: 

I    Sove  1 

llTEHPORDRV.T^d^^H 

C   Cancel  ) 

Push  Word  ManLen  ;  Max  1  muni  length  of  rsapons^ 

PuahPlr     ReplyRec  ;Pointcr    lo   reply  record 
_SFPutFj  le 
RTS 


Mirny  of  tlif  rAmf  types  of  parjimettrs  usr-d  by  SFCttFilt?  art-  also  used  by 
SFPutFile.  Tlie  ncv.  p:irameters  used  by  SFPiitFiic  art-  OrisNiiinc,  a  pniiUc-r  to  the 
default  fileiimite.  And  MaxLcn,  the  tnaxinium  length  of  tht"  filename  to  he  entered. 
In  mns.t  cimimstiliicei,,  yOu  will  want  to  set  MaxLen  to  1.5,  the  maximum  length  of 
a  ProDOS  filename. 

If  the  name  selected  (by  clicking  the  Save  button)  is  already  bein^  used  as  a 
subdiret-tory  iianif.  SFPutFilf  displays  an  "(  Ciin't  Destroy  ii  Directorv"  tlialoy  box 
with  ail  OK  button.  Another  name  can  lie  seleLled  after  the  OK  buttou  is  tlicked. 
If  the  name  is  already  beinm  used  by  a  iionnal  data  file.  SFPutFile  displavM  a  "Replace 
Esistrnj;  File':'"  diiilofi  hox  with  Vrs  tind  \a  huttons.  If  _\n  is:  clicked,  another  name 
can  be  ^ielectcd;  if  Yes  ii  eliL-ked.  SFPutFilf  ejids. 

SFPutFile  also  ends  when  the  Caneel  button  is  dieked  or  when  a  unique  filename 
is  entered  and  the  Save  button  is  elitked.  The  Co(k1  lield  in  the  reply  record  is  false 
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if  the  Cancel  button  was  pressed;  othervi'isc,  it  is  true.  If  a  name  was  entered,  it  Is 
ittunied  in  thr  filename  fielil,  and  tht-  pathname  field  coiitains  th*?  cumplete  path- 
name, lii  addition,  the  selected  directoiy  in  as.sipned  to  prefix  OA 


REFERENCE  SECTION 

Table  RlD^li    The  Parameter  Tahlea  lor  the  FroDOS  16  Commands  

note:  In  ihesc  tables,  an  Input  (I)  U  a  paminrrlcr  lha!  mia^i  he  provided  before  usirg  the  commarnl. 
A  Result  [Rl  is  a  pamnietei"  returnecJ  by  the  comrrand.  If  the  Result  is  3  sttingr  you  must  aUocalc  a 
ipacE  for  the  string  that  will  tie  returned  aJitl  ptmide  a  pointer  to  it, 


ALLOC.INTERBLiPT  (S31) 

Input 
Symbolic  or 

Offset   itfflTW  Result  DescritJtion  

+  0  to  +1  int_num  R  Int^Trupt:  handler  reference  number 

+  2  tit  +5  int_codf  I  Pointer  to  internipt  handler 


CHANGE.PATH  ($04} 

Input 

Symboiic  or 
Offset  Nairw  Reauit  Descriptum 


+  0 1«  +3         pathname  I  Pointer  t<j  the  pathname  string 

+  4  tP  +T         new_pathname       I  Pdintcr  to  the  new  pathname  string 


CLEAR^BACKUP_B[T  [40B) 

Input 

SymbvHc  or 
Offset  Name  Result  Descripiian 


+  0  to +3         pathname  I  Poiivter  to  the  pathname  string 
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CLOSE  ($14) 


Off  net 

Sijmbolic 

Input 

or 

r^f.^^  rinti  *  >ti 

+  U  to  +1 

ref  nil  111 

I 

RGfcrG'nC&  numtjifr  for  the  file 

CT/tr ATC  ^-em^ 
Offset 

Syinbotic 
Nonw 

Itlpllt 
cjr 

Remit 

Descriijiion 

+0  to  +3 

patKnaine 

1 

Pointer  In  ihe  pathname  string 

+  4  to  +5 

access 

I 

Access  code 

+6  lo  +7 

file  _  type 

1 

rile  type  code 

+  8  to  +11 

atix_type 

I 

Auxiliary  type  code 

+  12  lu  +13 

storage,  type 

I 

Storage  type  code 

+  14  to  +15 

t.Teatt_date 

I 

Creation  date 

+  16  t(!  +17 

creatc_lime 

I 

Creation  time 

DEALLOC.INTERRUFT  (&32) 

Symbolic 
Offset  Name 

Input 

or 

I\csutt 

Description 

+0  to  +1 

int_nuin 

I 

IntecTUpl  handler  re^ferenL-e  number 

DESTROY  (S02] 

Si)mhul  it- 
Offset  Name 

Input 

CJr 

Result 

De!:criptwn 

+0  to  +3 

pathname 

I 

Pointer  to  the  pathname  string 
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FLUSH  ($15) 

Input 
Symlfulic  or 
Offset  jVame  Resiiif  Description 


+0  tn  +1  ref_niim  I  Referent*  number  for  the  file 


FORMAT  (m) 


Offset 


Sy  rnhaiic 
Name 


Input 

ur 

Result 


Description 


+0  to  +3  dev_nanie  I 
+  4  to  +7  vo]_naine  I 
+  8  to  +9  fik'  svK_id  I 


Pointer  to  the  device  name  string 
Puitiler  to  tlie  volume  name  string 
Operating  system  ID  code 


GET_BOOT_VOL  (m) 
Symbolic 

Offset  Nairn  Result  Description  

+0  to  +3         data_biiffer  R  Pointer  to  the  voWme  name  strinj^ 


Input 

Symbolic  iir 


GET_DEV_NUM  {320) 

Symhnlir 
Offset  Ntimc   


+0  tu  +:] 
+  4  to  +5 


de\_iiiune 
dev_iium 


fnput 

iir 

Result 


Description 


1 


Pointer  tn  the  dpvit'e  name  strinK 
Device  reference  numher 
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GET_EOF($19) 

!nput 
Sijmbolic  01 
Offset  Naitie  Hesult  Destription 


+0  to  +1  ref_iium  I  Referent*  numhcr  for  the  file 

+2  to  +5         eof  R  The  end-of-file  position 


GET.FILE.IN'FO  ($06) 

Input 


Offset 

Symbolic 
Name 

or 

Restdt 

Description 

+0  to  +3 

pathname 

I 

Pointer  to  the  pathname  string 

+4  to  +5 

access 

R 

Access  code 

+  6  to  +7 

file_type 

R 

File  type  code 

+&  to  +11 

R 

Auxiliary  type  code  ["] 

+  12  fo  +13 

stiirage.type 

H 

Storage  type  cthde 

+  14  to  +15 

treate^date 

R 

Creatitm  date 

+  16  tn  +17 

L-reate.time 

R 

Creation  time 

+  16  to  +iy 

mod  _d  ate 

R 

Modifitiiitiun  date 

+  20  to  +21 

mod  _  time 

R 

MudifiLiitiun  time 

+22  to  +25 

b]ocks_used 

R 

Blocks  used  by  the  file 

[*)  Fai  a  volunif  diteclor);  lile,  this  field  becmni^ii  tctal_blocks  (the  jiuintKr  of  blcx:lcs  dd  the  volume). 
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GET_LAST_DEV  ($2il 

hifjul 

Symbolic  or 
Offset  iVfliiif   Result  Description 


+0  to  + 1  dL"V_T!iit"ii  R  Device  reference  number 


CET_LEVEL  ($1B) 

lnf)iit 

Stjmholic  or 
Offset  Num^  Remit  Descriplion  

4(1  tn  +1         level  R  The  Luirent  file  level 


GET^MARK  ($17) 

ttipiil 

SymlwUr  or 

Offset  S'ariw   R^mit  Dpstriplioii  

+Oto+i  rff_miiTi  I  Reference  number  for  the  file 

+  2  tn  +5         ptksition  K  Th^  currt-nt  mark  ixisitinn 


GF:T_NAME 

f  nput 

Hiimhoiic  fir 
Offset  ^ame  Result  Description  

+  0  to  +3         data_t)ufiref  R  Pointer  to  application  name  string 
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GET.PREFIX  (SOAJ 

Symbolic 
Offset  Name 


input 
ur 

Result 


Description 


+  0  tn  +1  prefix_miin  I 

+2  lo  +5         prefix  R 


Prefix  number  (0  to  7) 
Pointer  to  prefix  name  string 


CET.VERSION  ($2A) 

Symbolic 
Offsel  Nairn; 


Input 
or 

Result 


Dt'scriptiort 


+0  to  + 1 


versjnn 


PraDOS  16  version  number 


NEWUNE 


Offset 


Stimhulir. 
Name 


input 

or 

Result 


+  0  lo  +  i  ref_Tiutn 
+2  to  +3  enable_mask 
+  4  to  +5         newltne  cbar 


Descripiion 


Relerence  number  for  the  file 
Newline  tenable  mask 
Newline  character 


OPEN  ($10) 
Offset 


Sijriibulic 
Name 


or 

Result 


Description 


+0  to  +1 

+2  to  +5 
+  6  to  +9 


ref_num 

patlinainc 

nulLfteld 


R  Reference  number  for  the  file 

1  Pointer  to  thic  pathname  string 

R  Reserved  area  for  ProDOS  16 
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QUIT  ($29) 

Input 

Symhotic  or 

Offset  Name  Result  Description  

+0  to +3         pathname  I  Pointer  to  tiext  pathname 

+4  to  +5         flags  I  Retuni/Restart  flass 


READ  (Sl2f 
Offset 


Symbolic 
Name 


Input 
or 


Dextripiion 


+0  to +i  ref_riuiii  I  Reference  number  for  file 

+  2  to  +5  data_buffer  I  Pointer  to  start  of  data  biiffpr 

+  6  to  +9  request_cnunt  I  Number  of  bytes  to  read 

+  10  to  +13  transfer  count  R  Number  of  hvlfs  acitually  read 


Input 
or 

Result  Description  

+0  to  +1         dev_nuri  I  Device  reference  number 

+2  to  +5         datii_buffer  1  Pointer  lo  the  read  buffer 

+6  to  +9  block.num  I  Block  number  to  read  in 


READ.BLOCK  ($22) 

Symbolic 
OffuL't  Name 
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SET_EOF  tSiS) 


Offset 

Sifmbatic 
Name 

Input 

or 

Result 

Descriptum 

+0  to  + 1 

ref_mim 

I 

Reference  number  for  the  file 

+2  (o  +5 

eof 

I 

The  new  end-of-file  position 

St  l_rlLE_ 

INFO  ($05) 

Offset 

itymhotic 
Name 

Input 
or 

Rentilt 

Description 

+0  to  +3 

pathname 

I 

Pointer  to  the  pathname  string 

+  4  to  +5 

atri.'ess 

I 

Access  code 

+6  to  +7 

file  type 

I 

Pilr*  l"vnf*  ^*ruH** 
I.  LIL  '■j^c  ^Lnjt? 

+8  to  +  1 1 

I 

Auxiliary  type  code 

+  12  to  +13 

{not  used} 

+  14  to  +15 

crcate.date 

I 

Creation  date 

+  16  to  +17 

LTtatt-.time 

I 

Creation  time 

+  1S  to  +19 

inoil_flate 

I 

Madificatioii  date 

+20  to  +21 

niod_time 

1 

Modification  time 

SET_LEVEL  [SlAf 

Offset 

Sfftribolic 
Natue 

Input 
or 

Result 

Descripliott 

+0  to  +1 

level 

I 

The  new  file  level 
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DescriptiOf]  

Rtft'erencp  number  for  the  file 

The  new  mark  position 


SET_PREFL\  (SOS) 


Input 

Sijmbolic 

or 

Offset 

Name 

Result 

Description 

+0  to  + 1 

prf?fix_nui!n 

1 

Prefix  number  (0  to  7) 

+  2  to  +5 

prefix 

I 

Pointer  tu  the  new  prefix  strins 

VOLUME 

Input 

Stjmhoiic 

or 

Offset 

Result 

Description 

+a  to  +3 

dev_name 

1 

Pointer  to  the  device  name  string 

+4  to  +7 

vo!_name 

H 

Pointer  to  the  volume  mme  string 

+  S  to  +  11 

loti3,l_hltK:ks 

R 

Size  of  the  volume  in  lilocks 

+  12  to  +15 

K 

Number  of  unused  Hocks 

+  Ifi  t«i  +  17 

fiU'_syK_Ld 

R 

Operating  system  ID  tode 

SET.MARK  ($16) 

Input 

SymboHf  or 
Offset  .VflTiif  Result 

+  0  to  +1  rL'f_niiin  1 

+  2  lo  +5         position  1 
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VVHlTt:  tS13) 


Off. let 

Symbalir 
Name 

Input 
or 

Remit 

Description 

+0  to  + 1 

ref_num 

I 

Reference  number  for  the  file 

+2  tu  +5 

d;ita_  buffer 

1 

Pointer  to  start  of  data  boffer 

+6  to  +9 

retjuest_fiiii[ii 

1 

Number  of  bytes  to  write 

+  iU  to  +13 

traiisfer_counl 

[I 

Number  -of  bvte s  actuallv  wriCleii 

WBTTE.BLOCK  ($23) 

SijmboHc 
Ojfscl  \(imr 

Input 

or 

Remit 

Description 

+0  tu  + 1 

di"\  _I1UITI 

I 

DeviciC  reference  number 

+2  to  +5 

data_bufFLT 

1 

Pointer  to  write  buffer 

+e  to  +9 

blo(-"k_nuiii 

1 

Block  nuinbei:  to  be  written  to 

Table  RlD-2 

I'niDt.JS  16  Error  Codes 

Error 
Number 

Description 

$00 

No  emiT  occurred, 

$01 

Thf  ProDOS  command  iiiinilx-r  is  invalid. 

$07 

ProDOS     hiiiv.  Thi! 
ctjniniantl^  [rnin  insid 
that  till-  St-hfdiikrr's  t 

error  Tiiif^ht  uctur  if  you  iry  to  use  ProDOS 
:in  interrupt  handlfr  without  firiht  Llie^'kinj^ 
.□sy  HaK  at  SEll)<)FF  i>  (*, 

$10 

Tlie  specified  devict  Ciiiinol  I) 
idler  &  CET_DEV_NUM  com 

:■  found,  ProUOS  reports  this  error 
niiind  if  it  c-aniiLil  Locate  the  device. 

$11 

The  drvitt  H'fereiuf 
if  the  di'vicf  liiinibcr 

number 

j.*  ntii.  in 

invabcl.  ProDOS  reports  this  error 
its  list  iif  iicMve  device's. 
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jEiVror 

Number  De.tcripiion  

$25  Tlif  ProDOS  intcmal  interrupt  vecttJr  tahlt-  is  full.  ProDOS  reports 

this  error  alter  an  ALLOC_l\TEBRUPT  cumrnaiid  if  16  interrupt 

veeturs  have  dretiily  been  allocated. 

^7  A  disk  I/O  error  occurred  that  preveiitpd  the  jnoper  transfer  cif  data. 

If  you  gel  this  error,  the  disk  is  probahly  irreparably  damaged.  You 
will  also  set  this  error  if  tliere  is  no  disk  in  a  5  'A-luch  disk  drive, 
however. 

$28  The  specified  disk  dcvict-  in  nut  present.  Tliis  emir  occurs  if  you  ti^ 

to  aeeeis  a  secojid  5  'A  ineh  drive  when  only  one  drive  is  present, 
for  example, 

32B  A  write  operation  failed  because  the  disk  is  ■write-protected. 

$2E  All  operation  ftiilfd  because  a  dt.sk  conlainins  an  open  FiU'  was 

removed  from  the  drive,  PrnPf^S  can  return  this  error  only  for 
commands  that  involve  checking  the  volume  name. 

$3F  The  specified  device  in  not  connected  tn  the  system.  This  error 

occurs  if  there  is  no  disk  in  a  3  Vs-inch  drive. 

J40  Tlie  [iathname  5ynta.\  is  in\  alid  because  one  of  the  filenames  or 

diret'tor>  names  does  not  follow  the  ProDOS  naming;  rules  or 
beeause  a  partiaJ  pathname  was  specified  and  a  prefix  is  not  active. 

542  The  file  control  blutk  table  is  full. 

!M3  The  file  reference  number  is  invalid. 

$44  The  specified  directorv'  was  not  found.  This  meani  that  one  of  the 

subdirectory  names  in  an  otherwise  valid  pathname  does  not  exist. 

$45  The  specified  volume  director,  was  nnt  found,  fliis  error  occurs 

wlieii  you  remove  a  disk  from  a  drivp  and  then  try  to  access  it. 

$46  The  specified  file  was  not  found. 

$47  The  specified  Blename  already  exists, 

$48  The  disk  is  full. 

$49  The  volume  directory,  is  fulL  A  lolume  direetoiy  camiot  contain 

more  than  51  entries. 

$4A  The  format  of  the  file  specified  iis  unknown  or  is  not  compatible  with 

the  version  of  ProDOS  being  used. 
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Error 

Sumbcr  Description  

$4B  Tht!  storage  type  code  fur  ihc  FiL'  is  inviilid. 

$4C  An  end-iil-file  ctinditiyn  was  tncountertfd  diirinj^  il  re^ld  Ciperalioii, 

$4D  Tht  niarlc  pnsititjn  h  out  nf  ranj^e.  This  errar  {>ceurs  if  yiiu  attempt: 

to  pnsitmn  the  mark  pointer  ]iast  the  eritl  i>i  the  Kle. 

$4E  Aeeesi  lu  llie  file  is  not  iilluwed.  T)iis  error  occurs  when  the  aetiiin 

prohibited  by  the  access  code  hyte  is  requested.  The  access  wmrd 
controls  read,  wrile.  rename,  and  destroy  operations.  The  error  aUo 
occurs  if  ynu  try  to  d^cstrny  a  directory  Rle  that  is  not  empty. 

lS.5fl  The  file  is  already  open.  You  cannot  reopen  a  file  tlia,t  is  currently 

open, 

$51  The  directory  is  duma^ed.  ProDOS  reports  this  error  ■when  the  file 

count  in  a  direclorv'  does  not  match  the  number  of  entries. 

$52  The  disk  is  nut  a  PruDOS-fcirmatted  (or  Apple  111  SOS -formatted) 

disk.  FroDOS  reports  this  error  if  it  detects  a  non-ProDOS  directory 
structure. 


$53  A  parameter  is  invalid  because  it  Is  out  of  range. 

$54  Out  of  meniory'  error.  This  error  is  returned  by  the  QUIT  coTumand 

if  the  ProDOS  9  application  specified  is  too  3argc  to  fit  into  the 
allowable  ProDOS  ft  memnr>'  space. 

$55  The  volume  cx>ntrol  block  table  is  full, 

$57  Two  or  more  disks  with  the  same  volume  Tiame  are  on  one  line, 

This  is  a  "warning'  error  in  that  FroDOS  still  perloniis  the  operation 
on  the  first  disk  it  detects  with  the  volume  name  required. 

$5S  Tlie  specifietl  device  is  nvi  a  block  device.  ProDUS  supports  block- 

structured  devices  only. 

8^59  The  level  parameter  (passed  to  SET_LEVEL  command)  is  out  of 

range. 

$5A  The  volume  bit  map  is  damaged.  ProDOS  reports  this  error  if  the 

volume  bit  map  indicates  tliat  the  disk  contains  block::  beyond  the 
maximuiii  block  count. 
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Error 

Number  Description  

$5B  llleRal  pathname  (.haTiRf,  lliis  error  wcur^i  if  the  palhnaines 

spfcified  in  ihf  CHANCL_PATH  cnnimand  reier  to  two  diffcrt-nt 
volumes,  You  tan  only  move  files  between  direttories  on  the  same 
volume. 

SSC  The  specified  Hie  is  not  an  executable  system  file.  ProDOS  repurts 

this  error  if  you  attempt  In  use  QUIT  to  pass  c-ontrol  to  ii  filr  that  is 
not  a  Promos  Iti  systeiii  (ile  (S16.  code  $H3J  (EXE,  code  SiB5]  or  a 
FniDOS  8  system  file  [SYS,  code  $FF1. 

S5D  The  operating  system  specified  is  not  ava^ilahle  or  not  supported. 

ProDOS  returns  this  error  if  ymt  ilrc  FORMAT  to  formal  a  disk  witti 
a,ii  operatiuK  systfm  not  yet  supported  liy  ProDOS  1&  or  if  you  try 
to  run  a  ProDOS  S  system  program  when  the  SYSTEM/PH  file  is  not 
on  the  system  tlisk. 

S5E  fK\M  unjiiDt  be  renioved-  This^  error  when  vou  QUIT  a  Pr{)DOS  8 

applic-ation  if  the  ZttAM  RAM  disk  that  uses  auxiliary  memory  [bank 
$01)  cannot  be  removed. 

JSF  Quit  Return  Stault  ovcrflnw,  Pr[)DO;^  returns  this  errnr  if  you  try  to 

push  another  ptu^ram  ID  on  th<'  Quit  Return  Staik  (using  the  QUIT 
LtJmmamdl  when  ihf  Stack  alrt'ady  hai  16  eutrifs  on  it. 

.^60  It  i\  imposfiihle  to  determine  the  last  device  which  wa.s  atiiessed. 

This  error  can  only  be  rt-tumed  by  the  GET_LAST_DEV  eommaiid, 


NOTE;  If  a  QUIT  MiiRmand  results  in  aty  iTfir  ilif  eriaz  li.iIc  \i  not  relumed  to  the  i^ipiicaban.  Instead, 
thv  Ludf  upiwars  in  an  interat-llv*-  diaiii^  inn  an  the  strecr. 


Table  RIO-a:     The;  Major  Functions  in  the  Standard  Fde  Operations  Tool  hii-t($17) 


Functiun  Name 


Funrtioii 


SFHetFilt^ 


SUick 

I'a  I  II  meters 


WhereX  (W) 
Wh.-reY  (W) 
ProioptStr  [LI 
FilterPriJL  ilJ 


Dcicritilion  (if 
Paravieter 


Tup  left-hfittd  X  cnordinate 
Top  left-hand  Y  eoordiiiatr 
Ptr  to  prompt  string 
Ptr  to  filter  procedure 
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Function 

Stuck 

PescripticfTi  of 

I  (1 1  unit  tt.  r  a 

P  fl  Tli  ITli'ti^T 
J  [II  C'*U-'ir'J 

Type  Li  St  (L) 

Pti  to  type  list  table 

ReplyRccord  {LI 

Ptr  to  reply  ret'ord 

SF  Put  File 

SDA 

WhereX  (W) 

Top  left-hand  X  coordinate 

WhereY  (W) 

Tnp  left-hand  Y  conrtiiiiLite 

PrompiStr  (L) 

Ptr  to  prompt  string 

OrigNameStr  (L) 

Ptr  to  detatitt  nieniime 

MaxLcn  (WJ 

Maximum  length  of  response 

ReplyRcLord  (L) 

Ptr  to  reply  record 

SFSh  utdnwn 

S03 

[no  parameters] 

SFStartup 

$02 

UserlD  [Wl 

ID  tag  for  memory  allotiition 

DPAddr  [W) 

Address  of  1  pag^e  in  bank  0 

Table  RlO-4: 

Tilt  Major  Functions  in.  the  Schtwlul 

er  Tuol  Set  ($07) 

Fitnction 

Description  vf 

Function  Nduie 

Number 

Parameters 

Parameter 

Sch  Startup 

$02 

[eip  paiametersl 

SL'hijhutDowr 

S03 

[mi  parameters] 

SuliAddTask 

result  (W) 

Boolean:  added  to  queue? 

TaskPtr  (L) 

ptr  to  interrupt  hajidter 
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Lisling,  lO-l;    A  Subrouline  for  IxadinR  a  ProDOS  Kile  iiilo  Mcmor>' 


LoadFils  STflPT 

Us  1 ng       F 1 1 ePg  ta 
Using       Start  D'ata 

;   flak    lha  aaer   fgr   the   name  of    the  fi-lc   to  npefi: 


Pu^hUard  'i20 

PuahPlr  SFProFTvpt 
PLiahLtmg  *0 
PushLoTig  fO 
PushPtr  (faplyPec 
SFGetFi le 


!  It 

;y 

; pr  omp 1 

; ( no  f 1 1 ter  5 

;  (T10  file   typa  list) 

; repl y  record 


LDfl 


good 
Loadrt 


;Get   the  reaiilt 

(Branch  if   ;t  was  "Dpen" 


SEC 
RTS 


-.Bet   carry  if  "Cancel" 


Load  the  file   into  memory; 


Lo^dtt 


_DPEN 

LDA 

STfl 

STfl 

STft 

STA 


Dps  nPar  ms 

ref  nii'm 
r  ef  numl 
r  ef  riumS 
r  ef  nufTi3 
r  ef  num*! 


!Qp«n  the  file 

jOet    reference  number 

;  and  store  it   4  n 

5    other    parameter  tables 


_OET_EUF  EOFParma 


^ Ge t    size   of  file 


PHfl 

PushLCing 
PtiahNord 
Push Word 
PiiahLong 


EOF 
My  ID 


;  apace  for   r  e^u ] t 

;  Pu  sh  9  i  ze  of  file 
;  Program   I D 
;Loc  l(Ed 

;(nieana    nothing  here) 


HewHand 1 e 


Dereference  the  block    handle  s&  *e  can  get   a  pointer  for 
the  BEAD  rommand.   The  handle  returTied  by  NewHandle    is  still 
QT^  the  gtflct,    so  after   PHD/TSC/TCD  it's    located  at 
locatiora   SI>3:-IDG   in  direct  page. 


PHD 

TSC 
TCD 
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LDA 

STfl 
LDY 
LDfl 


[S031 

da  la_buf  f 

data  buff -2 


;Gi^l  poin t f I-   [  1  ow ; 


;Gel  pointer  (high) 


PLfl 


; Rest  ore  d. .  p . 

;  'Pop  NewHaTid  1  e  r  esu  1 1 


STft 
LDfl 
STfl 


EOF 

request 

IT  equesl  •  2 


iNiijnhe.r  of  bytes  to 
't   read   ls  set  by  EDT. 


_NEUiL1NE  NLParma 
Close  ClogeParma 


;Disable  riewlire  feature 

;6e^d    the    entire  file 
iC  loae   the  file 


CLC 
RTS 


iCairy  clear  means  "Open" 


END 

FileDats  DflTfl 
;    SFGttFilt  data; 
SFPfompt  STR 


'Select  a  file  to  wiew: 


ReplyRec 

good 

f  I  letype 

K  ty pe 
F I  1 eName 
fulipath 


DS 
D5 
DS 
D5 


Z 

129 


Non-iero   if   opcTi  pressed 
ProDGS  file  type 
ProDCS  auxtUary  file  type 
Name  of  file  kr  directory  0/ 
Fail  pathname 


\  Data  far   file   !/□  operations; 


OpenParms  flNQP 


ref  nu*n 


DC 
D5 


lI'FileName' 


;Reference  number  returned  here 

;Pointer   to  filename 

iSpace  for   1/0  buffer  pointer 


EDFParms 
r  ef  num 1 
EOF 


ANQP 

DS 

DS 


[EOF  returned  here 
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NLParms 
ref  numE 


RcadParms 
ref  nurn3 
dalB_biif  f 


C  loaeParms 
ref  rium4 


StartData 

My  ID 


DS 
DC 
DS 

flHDP 

DS 

DS 

D5 

DS 

ftNDP 

DS 

END 
□  ATA 
DS 
EHD 


2 
2 


;disable  ncwlirie  read  mode 


jPointcr  to  data  area 
[Number  of   bytea   to  read 
;4nkjnibcr  actually  read) 


iStare  finStartup  reault  here 


Listing  10-2:    A  Subroutine  for  Saving  a  Block  of  Memory  to  Disk  as  a 
ProDOS  File 


This  aubroutine  asks   the  user  to  enter  a  filename, 
then  saves  a  blocli  of  data  to  that  file  on  disk. 

On  antry,    da:  a_fauf  f /da  ta^buf  f +  2  polnlg.  to   the  start 
of  Ihe  tJata  buffer.   The   length  of  the  buffer  15 
stored  at  ac  t  ua  1  yact  ua  1  ^2  .    Theai;  variables  are 
c^F^finsd  in  the  FileData  data  segment. 


Savenia 


START 

t^sirg  nieDatfl 


;  Ask  the  user   to  enter  a  name  ior-  the  file: 


PushWord 

PushWord 

PushPtr 

PushPtr 

PuahWa  rd 

PuahPtr 

_SFPutFi 1 


#120 

Sa vePrompt 
FN_Defflult 

RcplyRcc 


; pr  omp  t 

^default  fil^riEiinE 
;1G  characters  max 
jreply  record 


LDA 


good 


:Qet   the  result 

iBronch   If    it   wa5  "Save" 


SEC 

RTS 


;Set  carry  If  "Cancel" 
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Savelt  ANQP 


;S4l  up  ^   pointer   to   the  area  to  be  lawed: 


LDA 
STA 
LDA 

5Tfi 


dfltfl_buf f 
w_buf  f er 
data_buf f +2 
w_buf f er*£ 


iSel  up  the  numb? r  of   bytes  t-o  be  -aawed: 


STfl 
STfl 


ac  tu^  1 
w_requeat 

ac  tua  1  -"2 


_CREflTE  CrestePrms 
_DPEN  OpiefiParm^ 
LDA  rBfnuni 
STA  w_refTiLiin 
STA  c  refTium 


Fi leData 


,HfilTE 
_CLD5E 

CLC 
RTS 

END 

DATA 


Ur  1 teParm^ 


jCreatfl  the  file 
\  Open   Ihe  file 


;Ulrite  data 


iCl^flr-    Carrv    if  "Save** 


SFPiitFile  datfli 


ReplyR^c 
gcod 


FUcHame 
f  Lil  Ipath 


flHQP 
D5 

ui 

DS 
DS 
DS 


3 

2 

2 

16 

129 


Non-iero    if   "Save"  pressed 
[not  ustdl 
[not  used] 
Filename  selected 
Full  pathname   iti  Q/ 


SavePrompt  5TR 
FN_Defaglt  STR 
;   Data  for    file   I/D  opera  t  i  (pn5 1 


"Enter  a  name  for  the  file:' 
'TEMPORflfiV.TXT'      jDefault  fUename 


CreatePrma  flUQP 
DC 

DC 
DC 


H'FlieHamei 
I2tS0'f' 


;Pointer  to  filename 
;acceg5  code 
iTXT  file 
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Dp  enParms 
ref num 


Writ  eParmp 
w_rcf num 
w_biif  f 
w„reqii4s.t 


DC 
DC 
DC 
DC 

SNDP 
DS 
DC 
DS 

SS 
DS 
D5 
DS 


CloseParms  ANOP 

c_refruin  DS 

END 


I  2<  0  ' 


]  4  ■  F  1  IcNaniE  ' 
4 


!  a  1  0  ragt  type 
;  cireal  ion  da  1 1 
;  er      t  Jon  t  ime 


;Reference  number   retiirne-d  here 

;PoiTiter   lo  filer>amt 

;Spac  p  fgr    I/O  buffer  pointer 


;PDinter   to  data  area 
jHymber  of  bytes  to  write 
{(number  actu^tly  writtenl 


Listing  lO-."!:    Tlie  StriKlure  of  an  SFGetFilr  Filter  Prncedvire 


*  This  15  a  filter  procedure  for  SFGetFile.  » 
4  ■ 

*  It  maltes   orly  TST  and  SBC  fi:ea   aeleclable  • 

*  from  a  file  list;,  all  other  file  names  are  * 

*  dimmed.  • 

*  On   entry,    here    is    what    l5.   on    the   ^tacli:  * 

*  * 

*  rBault{wardJ  i 

*  polTiter   to  directory  *Tilry   [long)  » 

*  return  address   (3  bytes]  ■ 

5F_Fi!ler  START 

;  Direct  page  offaeta: 

OldDP  FQU  SUl 

RelAddr  EQU  DldDP^S 

DirEntry  EQU  Betflddr+3 

Result  EQU  DirEntryH 

PHD  ;Savc  direct  page 

TSC 

TCD  jfllign  d.p.  with  stack 

LDV  flG  lOffset   tg  file  type  code 

LDfl  IDlrEntry] ,V 
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3«7 


FP1 


AHD 

*tOOFF 

;  (use   low  byts  onl/) 

CPlP 

BEQ 

r  HIJ 

iV^i^      i-o  branch 

CMiP 

«  *  rt  d 

BEQ 

FPD 

LDfl 

#1 

r  r  1 

|_Dft 

;2  •    di  9play/ae  t  table 

STA 

■Gave  the  result 

PLD 

;Re9tore  d.p. 

LDfl 

2.5 

;Movp  3-byte  retLirr 

STfl 

6,S 

i  address  up  by  4  byte*. 

LDA 

1  .5 

ST  A 

5,5 

TSC 

jftdd  1   to  the 

CLC 

;   stack  poiTiter. 

ADC 

TC5 

RTL 
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CHAPTER  11 


Sound  and 
Music 


One  (]f  the  remarkable  features  of  ihc  Apple  fins  its  ahilih^  to  create  intredibly 
realistic  sound  t-ffetts  and  music.  Tlie  i;s  tan  du  this  betause  its  sound  syslem  is 
coiitnilled  by  the  powerful  Eiisoniq  D\pu\  OsdlUtiir  Chip  (DOC),  the  same  chip 
used  in  the  pnifcssioiial-qadity  Mira&c  Digital  Sampling  Keyboard  Aivi  the  Ensoniq 
Piano. 

With  appropriate  software,  the  Ensoniq  DOC  can  generate  up  to  32  user-defin- 
ahle  sounds  sLinultanefMisly.  The  Fr<?quency  of  these  sounds  eaii  be  varied  over  a 
wide  ranjif  and  the  volume  can  be  .set  to  any  nf256  distrrete  levels-  As  a  result,  it 
is  possible  to  mimic  clnsely  the  acnustieal  beha\  ior  af  any  musical  instrument.  The 
DOC  is  iilso  capable  i)f  sauiplin^  incumiiig  audio  signals,  itichiding  vmce  samples, 
and  eonverting  them  to  digital  ffinn. 

S'ote:  Ti)  maintain  unmpatibility  with  earlier  Apple  II  models,  the  G-l  also  lets 
you  crcatf  simple  sounds  b\  tcpshnp  the  cs  speaker  with  a  soil  switch  lU  $R0C:030, 
You  can  use  the  SysBecp  iunction  m  the  Miscellaneous  Tool  Set  t<i  bt-t-p  the  ^^peaker 
using  thiii  techniipie.  SysBeep  requires  no  parameters. 

Tliis  chapter  takes  a  close  look  at  the  Ensoniri  DOC  and  examines  ways  of 
manipulating  its  intt-mal  registers  to  create  sound  and  Tnusic.  It  aUo  discusses  usitig 
tlie  Sound  .Manager  to  communicate  with  the  DOC  and  to  play  back  i>rerect>rded 
sound  patterns.  Finely,  ihe  Nute  Synthesizers  ability  to  play  musical  tunes  using 
different  sinnilatcd  instruments  ia  covered. 


SOUND  HARDWARE 

A  block  diajjram  of  the  cs  sound  system  is  shown  hi  figure  U-l-  All  sound-cnntml 
fomniandh  are  sent  by  a  program  ninning  in  the  65^1fi  address  space  to  the  Sound 
General  Logic  Unit  (Gl.U).  The  GLU  passL-s  tliein  im  to  the  snnnd  cirtuitiy  ton- 
trolled  by  die  Ensoniq  DOC.  Btcaiise  the  Ensoniq  is  isolated  from  the  65fll6  liy 
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Figure  1 1-1.    Tlic  Apple  llua  Stiurid  System  BlwV  Diasram 


system  vo-lume  control 


65816 


Saund 
GLU 


Ensonlq  DOC 
Bound  Chip 


&4K 
RAM 


speaker 


^eedpho^G 

jack 


channrl  ark^'ss  2 
chtmt]  ttidrtit  ilrntw 


7-pin  notex 
connector 


Table  1 1-1:    Thf  Sound  GLU  Registers 


Regviter  Name  Addresi- 

Sound  Control  SC03C 

Data  $CQ3D 

Address  Low  SCOSE 

Address  High  $C03F 


the  GLU  in  this  way,  it  can  generate  sound  indippcndcntly  of  the  current  apphcatiun 
nimiing  in  nncmiiry.  That  is,  the  application  can  perform  uthcr  tdnl-a  while;  iiound  iii 
pluy  in^  in  the  backgniund. 


Sound  CLU 

The  Sound  GLU  Lontsiin^  four  reRislers  fiir  c-oinmLinLcalin^  with  the  DOC  (see  table 
11-1).  The  Sound  Control  resiater  shown  in  figure  11-2  is  the  mast  complex.  The 
lower  four  bits  control  the  output  vohime  level  of  the  audio  amplifier.  Tlie  cs  sound 
tools  put  the  volume  level  (as  set  by  the  Control  Panel)  into  lliese  hits  before  they 
access  the  DOC. 
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Figure  11-2.    The  Sound  Contriil  Hegister 


7  1  e  5 

4 

3 

2  1  1 
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^  must  he  0 
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Bit  7  is  a  status  bit  thai  indicates  whether  the  DOC  is  ready  to  respond  lo  read  and 
write  operations.  It  is  readv  only  if  this  bit  is  0. 

Bit  6  Litntrols  whether  the  vaiuf  in  the  Sound  GLU  16-bit  address  register  refers 
to  an  addre!^s  in  the  DOC's  speeial  64K  HAM  waveform  buffer  (hit  =  1)  or  to  a 
DOC  repistnr  number  (l)ii  =  01 

Bit  5  controk  wht:ther  the  GLU  address  rcspsler  is  to  increment  automatically 
after  a  data  reRistcr  access  (bit  -  1)  or  whether  it  is  tu  stay  the  same  {bit  -  0), 
Setting  the  auto- increment  bit  makes  it  easier  to  access  a  range  of  registers  or  RAM 
addresses. 

The  16-bit  address  register  rantains  either  an  address  in  the  DOC  RAM  art-a  or 
a  DOC  reRister  number,  depending  on  the  stale  nf  bit  fi  iif  the  Sound  Cnntrol 
register.  For  register  aeee^s*^s,  the  hi^h-cirder  part  of  the  address  register  is  ignored. 

The  data  register  can  be  used  to  write  data  to  DOC  registers  or  to  DOC  RAM, 
as  well  as  for  reading  data,  Here  is  how  tu  read  nr  write  a  byte  of  data: 


1.  Adjust  the  value  in  the  Siiund  Register  to  icidiMte  whether  a  DOC  register 
or  D(}C  llAM  is  to  he  at-t-essed,  and  set  the  auto-increment  bit  to  the  desired 
state.  The  volume  bits  should  be  set  to  the  system -volume  value  (it  is  stored 
in  the  low-order  four  bits  nf  $E100CAj'. 
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2.  Store  the  DOC  register  number,  or  the  DOC  RAM  address,  as  the  case  may 
he,  in  the  address  registers, 

3,  Store  the  Hatii  hyip  in  the  data  register  (write  operation)  or  load  the  data 
byte  from  the  data  register  (read  operationj. 

One  caveat  shoidd  hr  incntioncd  that  afffct?:  read  optratioins  involving  the  DOC 
resiitiLTii  <ir  DOC  RAM.  A  rtad  operation  inimediatt'ly  follDwing  the  storing  of  an 
address  in  the  Sound  GLU  uddre^s  register  lags  by  one  cycle,  so  you  must  always 
if^nore  ihe  first  result  rftumefd.  If  aiito-iiifrcnipnt  is  nn.  vou  need  onlv  ignore  the 
first  result  in  n  se[[ijenc'e  of  sut'eessivc  read  operation.^. 

A  final  note  an  the  Sound  GLU  DOC  registers;  Apple  has  warned  developer's, 
not  to  access  these  rej^isters  directly,  because  their  functions  or  addresses  may 
change  in  future  versions  oi  the  t;s.  It  you  need  to  manipulate  the  DOC  registers 
or  DOC  RAM,  you  should  use  the  Sound  Ma^a^;er  hinetions  described  later  in  this 
chapter, 

Ensoniq  DOC 

The  Ensoniq  DOC  is  the  heart  of  the  t;S  sound  system.  It  ctmtains  32  independent 
oscillators  (tujinbered  fmin  0  to  31)  thai  can  be  used  to  samplt,  at  user-dcfinLible 
rates,  digitized  audio  WAvclbrn'is  stored  In  memory.  Thi^  sampling  mtt?  indirectly 
sets  the  frequency  of  the  sound  generated  by  the  oscillator.  The  DOC  has  a  total  of 
227  intimal  registers  for  toiilrolliiig  the  operation  nf  its  oscillators  and  of  the  DOC 
chip  itself. 

Because  each  oscillator  operates  independently  ol  any  ullier,  you  can  play  32 
waveforni.s  i;inndtanenns|y!  Th*'  t:,s  sound  tools  p^ir  tliese  oscillatori;  off  to  create  16 
Loicfx  or  ^encmfiu:',.  This  is  done  to  mak<?  it  possible  to  create  richer  and  more 
realistic  sound.^i.  One  iif  these  generators  (corresponding  to  oscillators  30  atid  31)  is 
reserv  ed  for  ujfC  as  a  general-pnr|insf  timer  by  the  cs  sound  tools. 

The  output  iif^nal  of  the  DOC  goes  to  an  aoiilog  ciri.iiit  thiit  amplifies  the  signal 
lietort-  sending  it  to  the  f'-S  speaker  (or  other  aodio  outpnt  device).  The  gain  ol  the 
amplifier  the  systcra  volume  set  bv  the  Sound  Control  register  in  the  Sound 
GLU. 

The  audio  waveforms  are  stored  in  a  64K  R.^\M  memory  area  dedicated  to  the 
DOC.  This  I'L'^M  does  not  llirm  part  of  ihe  f>5Slfi  address  space  anri  can  be  accessed 
only  throu^lh  the  Sound  tJLU  rejjisters. 

An  audio  signal  is  calle^l  a  iisaLi'ftinii,  btn  ausi'  il  you  plot  a  graph  of  signal  intensity 
(ainplilndel  versus  time  for  a  pure  tone,  you  get  a  series  of  sinusoidal  waves,  as 
shown  ill  Kjjure  11-3.  The  freijiiency  [or  j((fc7il  of  the  signal  is  expressed  in  cycles 
per  second,  or  ilt'i-tz.  As  far  as  the  DOC  is  concenied.  however,  the  waveform  need 
not  be  a  symmetric  ua\e  at  all.  It  could  have  a  wjmpletely  random  form  (white 
1103.sc)  or  a  t01liple?i.  btll  periodic,  funn  made  up  oi  a  ciimbinalion  cif  siimioidaJ 
waves.  By  playing  with  the  waveform  you  can  generate  all  sorts  of  interesting  sound 
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Figure  11—3.     Auclnj  Wavefurins 


variatiuns^  in  fact,  nns'  nf  the  reiisnns  different  musical  instruments  do  not  s^iimd 
exactly  the  Jiam*'  is  that  the  wavi^furins  they  f;f'nrrjtr  for  the  same  pitch  arc  different. 

A  di^itizt'cl  wavefiirin  stiired  in,  the  DtK^  RAM  areii  is  a  senes  iif  hytes  repre- 
senting the  aci|]htiid(;  of  the  siiund  wave  lit  fixed  time  intervals.  The  hytes  can  take 
on  values  fnjm  SO]  flow  vulume)  tii  SFF  (high  voliime).  A  DOC  useillatur  stups 
when  it  encounters  ii  SCK)  L»yLe. 

Sound  Output 

The  DOC]  throuE^  a  w-aveform  at  a  nscr-dc  fin  able  rate  and  feeds  the  bytes  it 

reatls  tn  a  built-in  digital-to-anakig  lunverter-  The  analog  output  fmm  the  converter 
goei  to  fiiur  tlifierent  destinations: 

•  The  buill-in  Iwo-itich  speaker 

•The  RCA  mini  headphone/spealcer  output  jack.  You  tan  oonneet  Walkman- 
sty]*:  headpKuricf^  ur  {with  an  adapter)  th*?  input  line  ol  your  stereu  set  to  this 
jaek 

•  Pin  3  of  the  7-pin  Molex  cWnneetnr  used  by  the  DOC 

•  Pin  11  of  the  RGB  video  connector  (this  is  for  the  benefit  of  KGB  monitors 
with  internal  speakers) 

Note  that  if  the  headphnne/speaker  jaek  is  in  use,  output  tn  the  speaker  is  autO- 
mbitioally  disabled. 

Sottware  that  creates  sound  usin^^  the  DOC  can  assign  the  sound  to  any  of  ei^ht 
output  channels.  (The  DOC  actually  fan  handle  up  to  sixteen  channels^  but  the  GS. 
supports  only  eight  of  them  )  The  channel  address  appears  on  pins  4,  5,  and  7  of 
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Table  11-2;     Tin-  227  iLii^Kiiii  VOC  Rrj^isters 


Re<iister  Nome 


FrequpnL'V  Lnw 

Frequency  High 

Volume 

Data 

Address 

Control 

Waveform 

Oscillator  Intt-rnipt 

Oscillator  Eniibk- 

AiialuB- to-Digital  Converter 


Number 


soo  +  osc 
sai)  +  osc 

S40  +  osc 
S60  +  osc 
S80  +  osc 
SAO  +  osc 

$co  +  osc 

$E0 
SEl 

SE2 


OSC  =  tht-  osc'il!att.r  number  (»00  h=  SlFl  Th.'se  -^n  ft-bil  re^slers. 


the  Mole,  ainneetc^r.  An  external  dcuniltiplexer  c.n  m^itar  this  address  ^-^^  e^t 
thr  output  sign.ll  (on  pin  3)  t=.  a  different  speaker  fur  each  channel,  The  MPIdeas 
SuperSan..  str^^o  e.rd,  for  .^ampl<f.  -orks  vvitli  Iwo  spr^ker.  sending  dUound 
for  even  -mmbcred  chaTUU^Is  to  oue  of  th*-m  and  all  sound  for  odd-nM,nbered  chan- 
nels  to  the  other. 

THE  ENSONIQ  »OC  REGISTERS 

Each  of  tb<'  32  CBullatnr.  in  the  Ensmiiq  DOC  h*s  seven  8-bit  rej-ist^-r.  .ssnciated 
v.ith  it  (s<-e  table  11-2).  Two  of  th^^sc  r^Sisters  .el  the  wavc-Fcvrn.  samplKig  rate 
(lreuueof:vl  of  the  oscilktor:  the  ntb.rs  .e.  the  volu.ne.  lh«  positkn.  of  the  osedktor  s 
waveform"  in  the  DOC  RAM  aK-..  the  ehur..lpn.tics  ol  the  wavefonn,  .nd  t  u 
o.cniatnr\  oper.timu.1  mode.  Finally,  one  register  contains  the  la.t  byte  the  ..se.llator 
Inadt^d  from  the  wavelonn  table.  .  , 

Therr  are  also  three  general-purpose  DOC  r^'Sist.rs  you  can  use  to  enable 
oseillunr..  read  interrupt  status  iuformatinn.  und  perform  analog-to^digital  c-onver- 
sioo  oi  incoming  iindio  sinuids-  ,  » 

Li,  total,  there  are  227  regif;ters  inside  the  En.oniq  DOC  eh.p.  The  sections  that 
follow  exainine  precisely  how  to  use  thfiii. 
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Oscillator  Reghters 

This  Keftion  discusses  the  seven  rt-Kislt^rS  assigned  to  c^lIi  osfilblor  Kf-L-p  iii  mind 
that  a-s  sliowii  in  tabic  11-2.  tk-  ret;istfr  nundjer  ibr  a  particular  oscillator  tl.e 
sum  i)t'  a  base  refristcr  number  ktnd  th^  oscillator  number.  For  example,  the  b^e 
reKister  number  for  Vnlume  is  $40;  thiTt-iure.  the  V'olune  reRister  for  oseillator  UC 
is  $5f:  tS40  +  SlCI. 

Freiiti^ncjt  Low  fSOO-SiF>  and  Fr^quenaj  Wi^h  ($20-$3F).  The  DOC -i  internal 
16-bit  frf{|iii-nev  rcgi-^ter  i.s  a  Loinatenalion  ni  the  Frif4ucney  Low  and  Fn-qu^ncy 
Hinh  recistf-rs.  The  value  stored  111  this  (xnnbined  register  sets  the  speed  at  which 
the  tmillator  retrieves  data  froui  thr  wavt-form  ill  memor>',  This  speed,  called  the 
svmplitcg  rate^  is  given  by  the  followinfi  Ibmiiila: 

(Scan  Kate)  *  F         ,    ,  . 
Sampling  rale  =   ^jTnn?—  "  ssmples/ second 


where 

T.  159  f  l(f    ,  J 
Scan  Rate  -  ;^V(5icrP2)j  ^''""""^ 

k,  ihcst:  formvilos.  F  represents  the  value  stored  m  the  l&-bit  frequency  register 
and  OSC  represents  the  number  of  enabled  oscillators.  RES  i<i  the  number  stored 
in  tht^  lesaUUifMi  hits  of  the  Waveform  rejijister  (see  belnwl. 

N.ile  that  the  samplinfi  ratf  not  the  same  the  frenueiicy  of  the  output  sigmU 
to  the  speaker.  Tills  freqiiene\-  depend;;  on  the  size  of  the  waveform  being  played 
by  the  oscillator  Tc  determine  the  trequeiicy  of  the  speaker  signal,  divide  the 
sampling  rate  hy  th.-  nurnher  at  bytes  needed  to  define  one  cycle  of  the  wavelor m. 

Volume  f$40'S5Fj.  The  Volume  register  sets  the  volume  of  tlie  oseillator.  When 
the  DOC  reads  a  waveform  data  byte  from  memory,  it  multiplies  it  by  the  value  m 
the  \  oluine  reKister  before  passing  it  to  the  mitpiit  amplifier. 

Data  iS60-$7Fi.  The  Data  register  contains  the  last  byte  the  DOC  read  from  the 
waveform  for  the  oscillator. 

Address  ($SO-Si)F}.  The  Address  register  contains  the  page  number  inside  the 
DOC  RAM  at  which  the  waveform  for  the  oscUlator  begins.  The  waveiorm  must 
start  oji  a  page  boundary. 

Controi  iSAO-!^BF).  The  Control  register  is  used  to  set  the  operational  mode  ot 
the  oscillator.  It  cuntrols  the  output  channel  with  which  the  oscillator  works,  whether 
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Figure  II— i.     The  Oscillator  Contrul  Register 
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I  =  hailed 
0  =  running 


osclllBtormode 
0  0  Free-Run 

0  1  One-Shot 

1  0  Sync 

1   1  Swop 

1  =  interrupt  on 
0  -  Interrupt  off 

chann&l  address 
(0  to  7) 


interrupts  are  i-nahled,  the  oscillahir  mode,  and  whether  the  oscillator  has  been 
halted  or  is  playing. 

The  meanings  of  eych  of  the  bits  in  the  Control  register  is  shown  in  figure  11—1. 
Tht  channel  addrest;  is  three  bits  wiJt  there  are  eisht  possible  output  chiiniiels. 
As  ihowu  ill  figure  Ll-1,  the  chaunt-1  address  lines  art  bnmyht  nut  at  tlie  T-pin 
Molex  connector.  By  Ltinnetting  a  multiplexer  to  this  connectDr.  you  can  easily 
generate  inultiphonic  sound. 

If  interrupts  are  enabled  for  the  oscillator,  the  interrupt  flag  in  the  Oscillator 
Interrupt  register  is  set  when  the  oscillator  Finishes  pkying  its  waveform.  In  addition, 
the  oscillator  numl>er  is  stored  in  bits  1-3  of  the  Oscillator  Interrupt  register. 

The  hiill  bit  controls  whether  the  nscillator  is  playing.  When  it  is  I,  the  oscillator 
is  halted  and  no  sound  is  generated.  When  it  iis  0,  the  oscillator  begins  playing  its 
waveform . 

Four  different  oscillator  modes  cm  be  used: 


Free-run  mode  [0).  In  free-run  mode,  the  oscillator  plays  the  wavefomn  again 
and  again  untJl  the  halt  bit  u±  the  Oscillator  Control  register  is  set  by  the 
application.  (The  oscillator  also  halts  if  it  encounters  a  $(X)  byte  in  the  waveiorm 
table.) 
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Figure  Il-S.     The  Waveform  Register 
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waveform  resolution 
(0  -  7) 

WQweform  table  size 

0  0  0  255 

0  0  1  512 

0  \  0  1024 

0  1  1  2043 

1  0  0  4096 
10  1  6192 
1  1  0  16384 
;  1  1  32766 


One-shot  mode  (1),  In  one-shot  mode,  the  oscillator  plays  the  wavefcrm  once 
and  then  sets  its  hall  bit  ant!  slups.  This  is  the  mode  you  wdulc!  use  if  the 
waveform  represents  a  lon^,  non-periodic  sound. 

SviK  mode  (2),  In  s-yno  mode,  a  pair  of  adjateiit  even/odd  oscillators  work 
toj^ether  in  sync'hrnnization.  (The  udd- numbered  oscillator  always  has  the 
higiher  iiuiiibcr  of  the  twot  Tn  partieukr.  when  ^he  even -numbered  oseilklor 
begins  playing  its  waveform,  the  odd-numbered  one  begin;;  playing  its  wavefarm 
as  well. 

Swap  mode  (3).  In  swap  mode,  as  in  sync  mode,  a  pair  of  adjaeeut  even/odd 
oscillators  work  together,  hut  in  a  different  way.  First  the  enabled  oscillator 
runs  in  une-shot  mode.  When  it  finishes  stepping  lhr[)njL;h  its  waveform  table, 
it  seti  its  halt  bit  and  then  clears  the  halt  bit  of  the  other  oscillator  so  that  it 
will  be!^in  plavin^  its  waveform.  An  even/odd  pair  of  oseillators  in  swap  mode 
is  called  a  netwralor. 

WavEform  ($CO-$DF).  The  Waveform  register  contains  the  size  of  the  vraveform 
being  played  by  the  osLillator  It  aUo  tells  the  DOC  the  resulution  of  the  waveform. 

As  shown  in  figure  11-5.  the  size  of  the  waveform  is  called  the  Tahle  Size  and  is 
represented  by  "a  3-bil  code  number.  These  codes  ctHTeipond  to  sizes  of  256,  512, 
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Figure  11-6.     Tlif  Usc-illsitdr  Iiittrmpt  Rc^isttr 
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1024.  304H.  4096,  fil92.  idm.  and  32768  bytes,  respet-tively.  No  othtr  sizes  are 
perifiittftl. 

The  \va\  t'f(irm  ir!inli]tinii  is  iilso  rppre5entec]  liv  a  3-hil  code  tiuiiilier  (ram  0  to 
7.  LiirJier  in  this  M.-clian  llic  ways  in  \i,h!i:li  Hiij;  val\ie  parlkipates  in  llie  vvavelorni 
sampling  rate  calciiltitiiiii  wtTf  disfussfJ,  If  thf  resolution  is  raised  bv  1.  the 
samplitij;  freciiienc)'  halved;  similarly,  if  jl  is  lowered  by  one,  the  sampling  ire- 
qiieney  doubles.  In  most  eases,  the  re.'^nliitkm  c'ldc  shmnld  lit  s^t  equal  to  the  Table 
Size  fode  so  that  tlie  effective  fretjucnt-y  of  the  signal  sent  to  the  speaker  is  not 
affected  b\-  powers  of  two. 

General  Registers 

The  fifllim  ing  three  registers  in  the  DOC  are  of  general  use  and  do  not  relate  tn 
any  specific  oscillator. 

Oticillator  Interrtipt  ($E0).  The  Oscillator  Interrupt  rejiister  indicates  whether  an 
interrupt  has  occurre  d  and.  if  sn,  which  oscilhilnr  caused  it  (sef  figure  11-6).  An 
interrupt  will  occur  M'hcii  an  nhcdlalor  finishes  pliiying  its  wavelonn  iJ'lhe  interrupt 
enable  bit  in  the  [K-icdlatnr's  Control  rcsi^itcr  is  set  to  1,  Bit  7  ciintains  the  interrupl 
flap,  Liiid  hits  1-5  fonfain  the  iniiTilier  the  oscMlator  that  caused  the  interrupt  {0 
to  31). 

Oscillator  Eiiahle  (SEI).  Thi.-;  register  enntrnis  the  nnmhi^r  of  enabled  oscillators 
(.■iff  figure  11-71.  This  ninnher  can  ran^e  frnni  1  to  32  anfl  is  stored  in  hitii  i-5  of 
the  register.  {The  niiiiiinuin  is  not  0  because  at  least  tine  nscillatnr  must  lie  enabled,) 
OsLtilators  are  enabled  in  numeric-  order,  starting  with  #0. 
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Figure  11-7.    The  Ostiltafor  E nahlc  Resi^t^r 


0     DOC  Register  $E  1 

 always  0 


number  of  oscillators 
enabled  i\  to  32) 

alweys  0 


Note  (liat  die  iiumbt-t  of  i  nalileti  nwilhitors  aftWts  thic-  rate  at  wlik-li  the  DOC  scans 
tht  oscilJutor  wave  tables.  Tht-  more  ostillators  are  enaljled.  the  sliiwer  llie  rate.  To 
simplify  talc-uktions.  the  t.s  miuntl  tools  eniible  all  32  oscillators. 

Analog-lo-Di^itai  Converter  ($E2).  This  register  contains  the  uulput  of  an  analop- 
tU'digitill  converter  whose  input  line  is  connected  to  pin  1  of  the  Molc^  cnnnedor 
used  hy  the-  Ensnniq  chip  (see  fifture  11-1!. 

To  read  iht"  rt  sult  of  the  iiualn^^o-diyital  cunversion  and  to  initiate  the  iiesl 
conversion,  all  you  have  to  do  is  read  thi^s  re^;istfr.  Th^'  convrrsion  pri>ee!is  takes 
about  31  micrweciintis,  so  do  not  read  the  rrp'^''*''"  asain  until  this  time  has  elapsed. 
If  you  do,  the  result  re;id  will  be  meaningless. 

SOUND  MANAGEK 

The  Sound  MiitiiEer  [tool  set  HI  lets  you  niiiiiipulatc  the  DOC  lefiislers  and  DOC 
RAM  in  siieh  a  way  that  you  do  not  have  to  concern  yourself  with  the  int^chanies  of 
the  Sound  CLU  or  the  1/0  addres.Se.'i  it  uses,  It  also  defines  and  lets  you  iisf  lj  free- 
form  svnlliesizer  which  is  useful  fur  pliiying  haek  diyitixed  sound  elVects  or  one  lous 
niusi{.'al  pietre. 

The  Sujud  Maiiilger  th^als  with  oseillutors  in  liwap  mode  pairii  culled  gvnerntors. 
SixSeen  geoc-ralors  arc  dchned,  bul  one  is  r**sfrved  ior  u^e  as  a  (inirr. 
Before  iisine  the  Sound  Maringer.  start  it  up  hy  caUio^  SonndStartiip: 

Push  Wo  rd  DPAddr  ;PDinter    to  one-page    in  bflTil:  IDO 

_SDundS  ta  r  tup 

The  direet  pa^e  work  area  v.'hose  address  is  passed  to  SonndStartup  must  be  page- 
ahgned. 

When  you  are  tbroiish  ^i'h  ^he  Sound  Manager,  call  SoundShulDown  i.oo  pa- 
rame  ters),  It  shuts  otTull  ihe  DOC  osLillator?. 


Accessing  the  DOC  RAM  Area 

Before  yuu  unn  creato  sound  with  the  DOC,  there  must  be  a  wa^  efitrm  in  the  DOC 
RAM,  You  can  put  one  there  w-ith  WriteRamBlock: 

PiJShPt^'     MyUftve  iPointer   t-o  wave  data 

PiishWord  #H!OOQ  iStartlng  address    i  r  DOC  RAH 

PushWor-d   #t.100  ;Si;e    of    wave    in  bytes 
_WriteflaimHlocli 
RTS 

riyUawe     DS  ?SS  ^Inaertwavedefinitionhere. 

The  low-nrder  byte  nf  the  starting  address  passed  tii  WriteRamBlock  should  be  $00. 
betauae  the  DOC  expects  waves  to  begin  on  page  boundaries.  The  wave  size  should 
be  SI(XI.  -5200,  .S4C0.  S8(K),  $1000,  $2000,  $400C),  or  $8000,  bemuse  these  arc  the 
only  sizes  the  DOC  support.^, 

The  waveform  tan  ttjniain  any  series  of  one-byte  valuta,  but  it  inuit  nt>t  contalii 
a  $00  byte,  because  a  DOC  mcillator  stops  playinp:  when  it  encounters  a  0  vahie. 
The  mid-range  vaJut-  iif  $80  corresponds  to  a  0  output  xollaj^e.  Listing  11-1  sh',>ws 
how  to  create  two  tyju's  iif  Himplc  one-pape  waveforms,  a  soiu&uidal  wave  and  a 
triangular'sliaped  wave. 

To  read  data  Ironi  DOC  RAM  to  main  mcniory.  use  ReadRainBlock; 

PushPtr  MyBuffer  sPcirvltr   to  buffer    in  mair  memory 

PuahUlord  ii(!111)0D  ^Starting  address    in  DDC  RAM 

PushWard  #140D  iNiimber  of  bytea   to  transfer 
.SeadRarnSlocfc 

Voliune  Control 

The  Sound  Mjiiagpr  has  two  func-tions  related  to  volume  settings:  GetSound Volume 
and  SetSiJundVnbime.  They  can  be  used  tu  read  or  set  die  vohiriie  level  of  anv 
generator  or  the  system  volume. 

To  read  the  volume,  call  GetSouiidV'oIume  as  follows: 

PHS  ;apacc  for  result 

PuahWord  CenNum  ^generator  number 
_Ge[EoundVQliime 

PLfl  i^^P  the  volume  setting 

If  Gen.Num  is  between  □  and  14,  it  represents  a  generator  number,  and  the  volume 
number  for  that  penerator  is  returned  on  the  stack.  The  volume  number  can  range 
from  0  to  2-53. 

If  GenNum  is  greater  than  14,  the  system  volume  is  returned.  The  system  volume 
raniE^es  from  0  to  15  only  and  is  returned  in  bits  4-7  of  the  result. 
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You  can  set  the  volume  <5f  it  particular  generator,  ai  the  system  volume,  with 
SetSoundVolume; 

PushWard  VolLevel  jVoJumE    level    {□    to  15) 

PushUord  GenNum  j&efieraLor  number 

_5etSoiindVQlumc 

As  with  GctS(niTid\'(iluine,  if  llie  generator  number  is  above  14,  ihp  system  volume 
IS  afFcctcd  iind  tht  voluilie  code  inust      stored  in  bits  4-7  of  VnlLevcl. 


Free-form  Synthesizer 

The  Sound  Manager  supports  a  free-form  synthesi/^r  you  can  use  to  play  back  any 
digitized  sound  stored  in  the  DOC  RAM  area-  It  i^  intended  fur  the  playback  of 
complex,  non-repeatable  wiivcfonlis  that  have  previuusly  been  digllized.  To  play 
musicjil  notes,  it  is  much  more  oonvenit'nt  to  nue  the  Note  Syiilhesizer,  as  we  will 
see  below, 

Th^e  main  fi-ec-ffirm  synthesiser  function  in  FFStartSound.  It  allociites  a  particular 
generator  and  causes  it  to  start  playing  a  wavefurm  stured  in  memory,  Here  is  how 
to  call  it: 


PiishUord  *GerHLLm'ESG+i01 
PuahPtr  FF.Parms 

.FFStart^QUTid 


;Generfltor  (high),  mode  (low) 
;pQiTiter  to  parameter-  block 


fF.Parms 


flNQP 

DC 

!  4  '  l^lavBFo^lIl ' 

jPointer  to  vi^M^iorm 

DC 

;5lzc  ai  waufform   m  pages 

PC 

12 ' Frequency' 

;PLByback  rate 

DC 

I2fD0C_flddr ' 

;DQC   position  for   wa v e 

DC 

I2'BiiffefSiie' 

;DDC  wave  size  cads 

DC 

;P[3lnter    Id    neitt   parm  tabit 

DC 

I  S  '  Volume ' 

iGsneralor  uolume  (0-255) 

The  Brit  parameter  passed  to  FFStartSound  contains  the  generator  number  (0  to 
14]  io  the  bipli-order  byte  and  a  m<ide  mde  of  $01  in  the  low-ordtr  byte.  The  value 
SOI  means  the  generator  is  used  for  free-form  synlliesizer  luodc 

The  parameter  table  tells  the  free-form  synthesizer  all  it  needs  to  know  about 
the  wavelbrm  to  be  played.  WaveForm  is  the  address  of  the  wavefomi  in  the  65816 
memory  space  and  WaveSize  is  its  size  in  2.5G-byte  pages. 

The  Frequcjicy  field  eontdins  the  number  lo  be  placed  in  the  DOC'i  frequency 
register  for  the  two  oscillators  in  the  generator;  this  value  tan  be  determined  using 
the  following  formula: 


32  *  SamplincHale 

Freciueiify  Hegister  = 


The  sampling  rate  is  expressed  in  tycles/secocid  (Htrtz)  in  this  fnnnula, 

DOC:_Addr  tht-  startins  address  in  ihv  DOC  RAW  are;i  ttv  which  tlie  wavt-fiirin 
is  (o  h(y  tninsferrrd  ht-fbrt:  it  is  played,  B(ifli-rSi«-  is  a  code  frcim  0  to  7  representing 
i^hr  Tablf  Slzr  of  tht  form.  {Sfi-  the  distii^sidii  urTable  Sizt:  in  c-anneetion  with  the 
nOC  VVaveibriTi  reRisters  t-arHer  in  this  chapter.) 

N<-xtWave  is  tht-  address  of  the  paranH-ter  Ulttek  for  fhc  waveform  to  \tc  played 
when  the  current  wavelnrni  liay  Wil  finished.  Set  it  to  0  for  the  last  parameter 
hlnek.  If  yoii  WiHil  to  play  one  wavt  uverand  over  ipiin.  set  the  NeittVVave  parameter 
to  the  address  «f  the  one  and  only  param<'ter  table,  [Ynu  ean  stop  the  snund  with 
FP'StopSonud.l 

Volume  is  the  volume  of  the  wavefnrin  and  t-an  raniJe  from  0  (low)  to  255  (hish). 
Four  other  major  functions  eaii  be  used  to  contm]  the  ffee-form  synthesizer  or 
to  check  its  status: 

■  FFStopSound  stops  one  or  more  generators 

•  FFSouiidStatus  checks  the  status  of  all  generators 

■  FFf^cneratorStatus  ehecks  the  ritatus  of  one  generator 

•  FFSiiundDoneStatus  detcrrnines  if  the  synthesizer  i^  playing  a  wavefnrni 

Two  minor  fuMftiuns.  SetSnnndMIitOV  and  SetUserSoundlHQV,  arc  used  to  install 
special  sound  interrupt  handlers  and  iire  rarely  used  by  applications.  They  are  not 
discussed  here. 

You  tan  iLse  FFStopSound  io  stop  any  penerators  that  may  still  be  running; 

P Li 5 ItiW o r d  OenMask  ;Generator  magk 

_FFSt  QpSouTid 

Eaeh  generator  correspotuls  tu  a  uni<ine  hit  in  the  generator  mask;  hit  0  for  generator 
#0,  bit  I  for  generator  #1.  and  so  on.  To  stop  a  pirtieulai  generator,  set  its  hit  in 
the  mask  to  1,  For  esainple,  to  slop  :ill  15  usahle  senernlors.  urc  a  mask  of  SiTFFl', 
Bit  15  of  the  inasli  corresponds  to  the  reserved  generator,  so  it  must  always  he  !J  in 
the  mask. 

To  detrrmme  whieh  generators  arc  planng  at  any  given  time  and  which  arf  idle, 
usr  FFhioiintlJilatus: 

PHA  iSpace  far  result 

_FFSoLjndS  ta  tu5 

PLf^  iPopttiegsneratDr  ma  5  li 


402     Souiul  'ini!  Music 


FFSmmdStatus  rctums  h  generator  mask  that  is  iif  the  same  form  as  the  one  p^^d 
to  FF  Stop  So  11  rid.  If  a  bit  is  se^t  lo  1,  the  generator  corresponding  tu  that  bit  is 
t^urrcntlv  plaving- 

FFGencrdtorStatus  returns  the  first  two  hytcs  <i{  the  generator  control  bhck 
(GCB)  for  the  generator.  These  byH's  mntain  tht  synthesizer  made,  generator 
numher,  ^nd  channe!  iiumbiT. 

Tlie  C.CB  is  a  lfj-b>  te  data  struLturo  used  by  the  free-form  synthe-siitfr  to  keeji 
trac^k  of  the  attributes  bind  status  iit  thi-  gt.neriUnr.  The  GCB's  for  eaeh  iil  (lie  sixteen 
geiierators  are  stnrt-d  in  the  nne-piigr  dire..t  pacf  are;»  wkiie  address  is  passed  to 
SoundStartup. 

To  call  FFGencratorStatus,  pass  it  the  number  (ifthe  genemtor  in  (juestion: 

p^^  ;5pacefDrr'eSLllt 

PLiahWord  GenNLiirber  iGeneralor  nymber 
_FF0ereralprSlflt'U5. 

p\_/\  -.Pop   ttie  slalu5  wQT-d 

Bits  0-3  of  the  status  wort!  eontaiii  tht-  jienerutiir  numhtT,  bits  4-T  contain  the 
output  c-hanriel  nuinlier  (normaJl>  0)  and  bits  eoiitain  the  mode  tode.  The 

mode  e-ide  is  SI  for  the  frtc-fcinn  synthesizer.  Bit  15  is  set  to  1  if  the  last  block  of 
ihe  wavefbrni  has  been  loaded 

The  last  major  free-lonn  funtlion  is  FFSoundDonL'Starus.  Call  it  to  determme  if 
A  frec-tbnn  synthej-iieer  gotieratur  is  currently  playing  any  thing: 

PHft  t apac  e  for   rs^u  1 1 

Pu  ahWord  GenH amber  ;  generator'  number 

_  F  F  5  o  li  m  d  D  0  ■n  e  S  t  a  t  a  5 

PL;^  ;Bu  =  y  cude 

If  the  result  is  $0000,  the  generator  is  still  playing;  if  it  is  SFFFF,  it  i,s  done. 
Low-level  Access  to  DOC  Registers  and  DOC  RAM 

As  mentioned  earlier  in  {his  thtlpter,  you  .should  nut  use  the  Sound  ULLI  registers 
to  commuTiitittc  direully  willi  the  Ensonig  DOC  registers  or  RAM.  instead,  you 
should  ose  the  Sound  Manager's  GetTable Address  fonLtion  to  get  the  address  of  a 
table  containing  thf  addresses  of  six  low-level  DOC  t-ontrol  suhmutines;  you  should 
then  call  ihesn'Mihroutines  to  eoininunieate  with  the  D(J€.  GetTableAddress  also 
returns  the  addresses  oftwij  uselul  oseillator^generator  transiatiOTl  tables  and  a  table 
□f  CCB  offset  addresses. 

Here  is  how  to  tall  CetTalileAd dress: 

PHft  l^pacfiforreaalt 

PHfl 

GetTableflddreaa 

PopLoTig  DnC_TablE  iPflp  pointer    to  table 
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TabJe  11-3:     Tlif  U>w-level  DOC  Siibmutint'  Table  Whose  Address  Is  Returned 
liy  CetTahlfAildress 


Siiifiiiutinc 
in 

T tibli:  Pii'mtiT 

R*'ad  Register 

$00 

Write  Rt'gister 

504 

Head  mw 

SOS 

Write  RAM 

Head  \c'xt 

$10 

Write  Next 

%U 

OscLlJatnr  Table 

Slfi 

Generator  Table 

Sic: 

GCB  Tablr 

$20 

DOC_Table  sliould  be  a  direct  pajje  variable,  sd  that  you  can  use  it  tcj  indireclly 
aecess  tht  contents  of  the  table. 

The  format  of  the  table  whose  addrt-ss  is  returned  In'  GptTableAddress  is  j(howii 
in  tiiblr  11-3.  It  e£mtains  nine  J-in  te  uddresses  [luw-ordur  bytes  first]  nf  low-level 
DOC  subroutines  or  data  tables. 

The  first  si\  entrie.'i  in  the  table  arc  4-byte  addresses  of  subroutines  [Imv-order 
bytes  fir^^t)  tlial  tan  be  talk-d  with  a  JSL  iiistrijctitm.  Unfcirtnnately.  the  65816's 
indireet  Inng  addressing  mode  is  useful  only  if  you  knuw  in  advance  where  the 
address  table  is  IoLat<.d.  aTid  you  do  nut  have  this  inlbrniation.  The  easiest  way  to 
tall  a  subroutine  is  to  .store  its  address  in  the  3-byte  uperaiid  of  a  JSL  instruction, 
low-Order  byte  first.  This  involves  ugly  self- modifying  code,  but  there  is  no  easy 
alternative. 

Fur  example,  here  ia  htjw  to  set  up  a  JSL  to  the  write  subroutine  (at  iDllset  $04): 


TablePlr       GEOU  *00  ;pointer    to    lo«-lcvel  table 
PHA 

_GetTablefiddrEas  ;&Bt    table  pginter 
PopLong  Tabl eft  r 
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LDfl  [TablcPtrl 

CLC 

ADC  #104 

STA  JSL.Patchtl 

LDY  #2 

LDfl  [TablePtrl ,Y 

ADC  #0 

SEP  #i20 
LDNGPl  DFF 

STfl  JSL_P3tch+3 

REP  #1£0 

LDNGfl  aw 

RTS 


jSL.Patch  J5L 
RTS 


; Get  address  (low) 

;  .  .  .    add  offset 

iSet     low    word    cf    Optra nd 

;Get  addj-eas  (high) 
l(fldjuat  for  any  carry) 

;B-bit  BCCLimdlBtor 


;Save  bank  byte 
l1&-t}it  accumulator 


;Call    low-leuel  subroutine 


Bi-fnrc  3  DOC  siibroiitine  is  called,  the  must  bf  in  native  mode  with  Ifi-btt 

index  registers  (s=0)  ajid  mi  8-bit  accumulator  (m=  It,  If  yuu  arc  in  full  native  modi:, 
you  can  switch  to  an  S-bit  accumulator  with  the  fnllo>ving  assembler  instructiuns; 

SEP  #120 

LDNGA  OFF 

After  you  call  the  .suhroutine,  yoii  can  switch  back  to  a  l6-bit  aL'Cumulator  with  a 
REP  #S2(>  in^itrDclitm.  follmved  by  a  LONGA  ON  directive, 

The  Oscillatur  Table  entry-  is  a  pninter  to  a  16-b)  te  generator-to-QScillator  trans- 
lation table.  This  table  cuntains  a  list  tif  nnr-bytc  oscillator  numbers,  in  generator- 
number  order.  The  sttimd  oseillator  for  a  given  f;enerator  is  always  the  next  higher- 
numbered  une.  For  example,  to  deteruiine  tbt;  two  oscillators  for  generator  you 
would  use  a  code  frasmenl  like  thii: 


QacTbl 


6E(5U 

LDV 

#tie 

LDS 

tTablcPtr J ,Y 

;Cet  psinter 

( low] 

STfl 

|]scTh  1 

LDV 

#Slfl 

LDfl 

[TflbUPtr]  ,Y 

;  Get  pointer 

(high; 

STfl 

05cThl+2 

SEP 

jSwitch  to  8- 

-bit  accumulator 

LDNGfl 

OFF 
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#9 

LDA 

ta^cTbi ] 

;G<:t   fjrat  oscillator 

STA 

Dscl 

;  Save    nu mtie r 

INC 

;5econd  oscillator  -  first  +  1 

STfl 

D5c2 

; Save  number 

REP 

#*2D 

;Bact:    Id   1&-bit  accumulator 

LDHGft 

DN 

RT5 

The  Generator  Talflt- 1- ntry  points  to  a  32-byte  table  yuu  c-an  use  to  determine  which 
oscillators  are  asiOLiatrd  witli  vvliich  generators.  It  wjntsins  a  list  uf  ^enemtors  in 
OSC'illator-llUilltjer  grdcr. 

Tlie  t;CB  Taljlf  fnpfains  the  une-b>i<:  nflset  poKititms  tn  the  generatur  ctjntrol 
bl(x.ks  fbr  the  i5  usable  generators,  in  f?{"n<;rarar-nuiiilitT  (ji  dcr.  The  base  pnint  for 
the  offsets  i^i  the  acidrt-s*  of  the  bank  WK)  page  passed  to  SoimdStiU-tup.  M^isC 
applicalinns  have  no  need  tn  access  llie  Gt^B. 

The  izitfthnd-s  that  emi  bt-  us(k1  to  uall  the  &ix  low-level  DOC  subroulineii  are 
discussed  in  the  sections  below. 

Reud  Register.  €al]  this  SLbrtiutiuc  to  read  the  tunfetits  ol  aiiy  u£  the  227  registers 
in  the  DOC.  The  ref^tstcr  number  must  be  in  the  X  register.  The  contents  of  the 
specified  DOC  refrister  is  returned  in  the  S-bil  accumulator. 

Write  Register.  This  iubruutinp  stores  a  number  in  any  DOC  register.  The  rcKister 
number  miisl  be  in  the  X  register,  and  the  S-bit  accntnulator  cuntains  the  number 
(ti  be  written. 

Read  RAM.  This  iubrnutinr  reads  the  value  stored  al  any  location  in  the  DOC 
RAM  area.  On  entr>=,  the  X  register  must  cunlain  lheaddres.s.  The  value  is  returned 
in  the  8-bit  accumulator. 

Write  RAM.  This  subroutine  writes  the  value  in  the  8-bit  aeeumulator  to  any 
lt>cation  in  the  DOC  RAM  area.  On  ciilrj.  the  address  to  be  writien  tn  must  be  in 
the  X  register. 

Read  Next.  Lf  the  previous  low-level  call  was  Read  Register  or  Write  Register, 
this  subroutine  return.^  in  the  S-bit  aLcruinulator  the  data  in  the  next  DOC  register. 
If  the  previous  call  was  Read  RAM  or  Write  RAM.  it  returns  the  data  in  the  next 
RAM  loealioii. 

Wrife  Next.  This  ^i.!broutinc  is  similar  to  Read  Next,  but  it  returns  in  the  8-bit 
accnniulalor  the  contents  of  Ihc  ne.\t  register  or  the  nisst  RAM  Jocatton,  as  the  t^e 
may  be. 
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Using  Low-level  Subroutin^i^:  Digitizing  Analog  Input 

The  CON\'ERTl£H  program  in  listing  illustrates  how  h>  t-<ill  low-level  DOC 
subryiitintfs.  H  tligitiiies  an  incnminK  analog  signal  (which  appears  on  pin  1  nf  the 
Ensoniq's  Mtilex  tuiinector]  by  reading;  DOC  register  $E2  again  and  again  until  a 
32K  huBer  fills  up  or  until  ESC  is  pressed.  (To  play  the  smind  back,  ynu  would 
transfer  the  stLnipIe  to  DOC^  RAM  and  tall  FFStartSnimd.) 

Vuu  eaii  use  a  dcviee  such  as  llie  MDldeai^  SuperSonie  stereo  card  (witk  Digitizer 
option)  as  the  source  of  the  aiialos  signal  to  be  dijiitized.  Tlie  SupcrSonie  receives 
its  signal  through  an  i^CA  phono  toiincxtnr,  wbick  you  can  conncet  to  the  output 
line  of  a  radio,  tape  recorder,  record  player,  CD  player,  television,  or  a  musical 
instrumenl. 

The  CONVEBTER  program  uses  a  samplinj;  rate  of  approximately  1000  samples/ 
second,  but  it  eiin  b*^  changed  by  adjustinH  the  counter  in  a.  delay  loop  in  the 
DoSamplc  subroutiTie.  According  to  the  Nyquist  Sampling  Theorem,  the  sampling 
rate  .ihould  he  at  least  twict?  the  frerjuencv  oC  the  hiRhcst-fretiucnty  component  of 
the  sound  beiiig  recordedn  If  it  is  not.  the  sound  will  appear  distorted  when  you 
play  it  hifvk. 

The  CONVERTER  program  uses  the  JSL  patch  technique  for  setting  np  thr  call 
to  the  DOC  read  subniiitinc.  When  the  subroutine  is  tailed,  the  DOC  regi-ster 
number  is  in  X  and  m=l,  required 

NOTE  SYNTHESIZER 

The  free-form  synthesizer  used  by  the  Sound  Vfana^;er  is  most  useful  for  playing 
back  long  sound  patterns  tliat  have  been  previously  digitized.  It  is  not  piirticukrly 
useful  for  plsyinj;  inus,ic;al  notes  or  synthesizing  the  effect  of  musical  instruments. 

It  is  the  Note  Synthesizer  (tool  set  25)  that  you  will  n^e  most  often  to  create 
musical  melodies  on  the  GS,  [t  is  eapable  of  playing  illl  standard  musical  notes  u.ting 
the  eh araeteri sties  uf  any  instrument  you  care  to  define.  With  a  minimum  of  extra 
effort,  you  can  use  the  Note  Synthesizer  to  as&ist  the  application  in  playing  back 
setjiiences  of  nutes  in  a  song. 

The  general  procedure  for  using  the  Note  Synthesizer  to  pUy  a  pure  note  is  quite 
.simple  L 

1.  Load  a  waveform  into  DOC  RAM  (with  Write  Ram  Block) 
Get  a  generator  [with  AllocCenl 

3,  Play  the  note  (with  NoteOn) 

4.  End  the  note  (.with  NotcOff  I 
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DifFicuUiFS  arise  when  tlffininp:  the  characteristics  of  tlie  insbrument  to  bp  used  to 
plav  tht'  note.  This  rrqiiirea  iiii  uiidfrjitanditig  of  terms  sulIi  ADSR  rnvclnpc. 
vibratij,  piU-hhfnd,  and  ieuiilmit?.  Tin:  ijroccss.  of  defining  isn  instrumt-Mit  will  be 
dL':cii5SPd  later  in  this  chapter. 

Starling  up  the  \utc  Synthesizer 

The  start-up  functHiti  ibr  the  Note  Synthesizer  is  NSStartup,  Before  LidlinK  it,  vou 
must  tall  SiJu  Eld  Startup  to  start  up  the  Sound  Manajscr.  This  is  necessary  because 
the  Note  Synthe:siziT  ust-s  Sound  Maua^tfr  runLtions  to  pi'rforui  sotne  of  itn  chores. 
Here  is  huw  to  cill  NSSt;ir!up- 

Pu^hWc'T  d  Updfl  t        1  e  ;  Envelope  uprfa  te  /  interrupt  rate 

PiiahPlr     MySequencer  i Pointer    tg   interrupt  handier 

_H55tarlup 

Thf  UpdalL-Ratf  variable  defiiiirs  an  interrupt  rate  for  the  notes  played  bv  the  Note 
Synthesizer.  ThiJ  is  tht;  rate:  at  which  the  ADSR  [attack,  decay,  sustain,  release] 
envelope  for  the  instriinn'nt  selected  to  play  the  note  ii  generated.  {ADSR  envelopes 
and  instruments  are  described  beltnv.)  The  UpdateRatL-  varial^lr  rs  in  uiuls  uf  0.4 
Hz  and  .should  normally  rjn>;e  from  75  i30  Hz)  to  500  (200  Hz).  Tht-  higher  the  rate, 
the  better  the  note  will  sound,  hut  the  main  application  w-ill  be  inlcrnipted  mure 
ol'len  and  will  iippear  to  slow  down  while  music  is  plavinj^. 

Wiicn  ii  \f)te  S>nlhesizer  updnte  interrupt  otcurSn  the  svst(?ni  interrupt  handler 
calls  the  user-defined  MySequeneer  subroiitine.  Tins  suhruutine  can  keep  track  of 
the  number  of  tiinrs  il  has  been  called  and  tTirn  notes  on  and  off  at  the  appropriate 
times,  For  e.\amplp,  if  ihe  update  rate  is  ,30  Hz  and  a  note  is  to  play  fnr  one  half 
second,  MySetjuencer  would  wait  for  15  internipts  before  liiniinR  the  note  off  (and, 
in  most  eases,  turning  on  the  next  nute  in  the  song). 

Playing  a  Note 

To  play  a  note  with  the  Note  Synthesiser,  yuu  must  start  by  using  AllocGen  to  get 
a  generator  witli  which  you  can  work: 

PHfl  ^spaceforreault 

PuahUlord  GenPriority  ;generatDr  priority 
_fl 1 1 DcGe  n 

PLfl  ;Pop  genecatcr  number 

The  GenPrinrity  parajneler  passed  to  AJJocGeo  is  a  number  From  1  to  1£8  and 
represents  a  priority  code  fur  the  fienerator.  For  most  purposes,  ytiu  can  assign  a 
IJrinrity  of  127  to  all  allocated  Keiierattirs. 

The  priority  indicates  ihe  degree  to  which  the  generator  will  be  "slnlen"  by 
^uhscrjueiil  calls  to  .MlneCeu  if  till  generators  are  in  use,  (Generators  0  to  l^  may 
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Figure  II— H,     Wavt-fonns  for  DilTcrcnf  Musical  Inxtnimcnts 


s'l  i 


Piano 


Bells 


Clarinets 


be  allocated;  the  Sound  Maiiager  and  Note  Synthesizer  resen'e  one  generator  each  ) 
AlloeGen  first  tries  to  nllncale  a  generator  that  is  not  in  use  (priority  =  ()!.  If  it 
cannot  find  one,  it  steals  one  with  the  lowest  priority  that  is  less  than  or  equal  to 
GeiiPriority.  (A  geiienitor  with  a  priorify  of  J2R  eannnt  he  stolen,  however.)  AllocGcn 
returns  an  error  if  no  p^enerator  qualifips. 

If  AIIckCk'h  dw-s  allncatf  a  ;j;cmTat<ir,  it  asHi^n.'j-it  a  pri(jrity  of  (ienPrionty. 

Onw  vnu  have  allf^eiitL-d  a  geiH'rator,  vim  must  Inad  a  wavL-fiirm  fur  the  generSttir 
mt(>  mfmory.  For  siTTipMcitv,  ytiii  can  just  Inail  a  siiiipl*"  sinusoiilal  wavtf  Or  a  trianglt?- 
shapt'd  approximation-  Kf'f'p  in  mind,  htjwcver.  that  real  mu^iral  in;;triiTnf nts  have 
diffen-nt  wavt'^form^,  so  yuu  shoidd  usr  them  for  mure  realistic  sound.  The  wa^  efurms 
for  some  Lximmcm  instruments  are  shown  in  figure  11— Ji- 

To  play  the  note,  call  NnteOn; 


PushUlord 
PushUlord 
PustiUlor  d 
PushPtr 

_Nott  ''11 


GerHLim  ;generater  number 

Semi  tone  jMIDI    HEniitone  (freqiiercy) 

Vo  1  litne  1^01  Lime 

Mylnilrument  jPoinlet'  la  instrument  dBfimtion 


MIDI  stands  Ibr  Musical  Instrument  Digital  Interface,  an  intemaiwjnal  standard  for 
diig^ital  musied  devices.  MIDI  senutone  todes  range  from  0  tn  127,  whi?re  middle 
I'  is  fill.  Scmitonr  codes  for  other  nntei  can  h**  deducted  from  the  information  in 
tahlf  I  l-l. 

Thf  Volume  parameter  also  ranges  from  0  to  127  and  is  roughly  equivalent  to 
MIDI  i.<  loeity  [the  speed  af  which  a  nutf  is  stnuk).  Faeh  group  of  Ifi  units  tif  the 
volunifc'  parjmcti^r  forri->;p()nds  to  a  fi-d«?('tlii'-l  ehanyc  in  vulume. 

The  Myliistniinent  parameter  is  by  far  the  must  complex  parameter.  It  points  to 
a  parainettT  bhiik  that  descrilies.  in  nieticulon^;  detail.  ehanRes  to  lie  made  to  the 
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Table  II-4:     MIDI  SeinittHit.'  <:otIrs  I'setl  Ijv  the  Nntp  Synthesizer 


Octate  Code 

Pifrh 

iCithtn  Octoue* 

1  36 

c 

+  0 

2  4fi 

c# 

+  1 

3  60 

D 

+2 

1  72 

D# 

+3 

5  84 

E 

+4 

F 

+  □ 

F# 

+6 

G 

+7 

G# 

+S 

A 

+9 

A# 

+  10 

B 

+  11 

*AdcJ  theip  codes  lu  |he  SPrnilune  base  code  foi"  tllr  i>iiiivi'  Ix-jni;  used, 

basic  wavffnrni  when  playing  the  note.  By  adjusting  the  instrument  parameters, 
yuu  can  simulatic  the  charaiteristius  uf  any  musical  mstnimcnt. 

Hie  geueriil  form  of  an  instrument  definition  L  i.hi>wii  in  table  11-5.  An  actual 

example  is  sin)w^l  in  lislinR  11-3.  It  bii'pns  with  t]je  dt-finitinn  of  an  ADSR  envelope 
fnr  the  iiislrunient.  As  shmvn  in  Ryiire  11-9,  AOSH  stands  for  atUick,  diLtiv.  sustain^ 
and  release,  the  four  consetutivc  phases  a  wavefunn  passes  tfirougii  whtrn  it  is 
played.  The  ampHtudc  of  the  ADSR  rnvt-lope  at  any  K'vcn  tune  reprtit-uts  the 
maximum  amplitude  [vctlume)  ol'  the  underlying  waveform  fur  the  nnte;  the  waveftji-m 
is  still  ascillatiuR  at  the  proper  frequeney.  bnt  its  maximum  amplilude  is  heiug 
modulated. 

Tu  E^splain  the  meaning  of  attaik.  deeay.  sustain,  and  rtlca.se,  it  is  best  to  eunsidt-r 
cine  particular  instrument,  say  a  piano.  The  slope  of  tlie  attack  stage  is  pruportwmal 
to  how  hard  you  strike  tJit-  piano  key;  the  harder  >'nu  strike  it,  the  faster  l!ie  vulunie 
reaches  its  maximum.  Decatj  refers  to  the;  degradation  in  volume  after  the  attaek 
maximum  has  bfien  reached.  Sustain  refers  to  how  the  volume  thangcs  as  you  hold 
the  key  down.  For  a  piano,  the  sound  is  sustained  for  some  time,  Imt  gradually 


410    Sound  and  Mu&ic 


Table  ll-S:     The  Ii^stniment  Defliiitinn  Data  Structure 


Field  Name 


OJJset 


ADSR_Enve]ope 

ReleaseSegmen  t 

Prio  ri  ty  I  n  ctc  m  en  I 

PifdiBendHiinge 

VibratnDepth 

VibratoSpeetl 

Spare 

AWaveCount 
BWaveCount 
AVVaveList 
BWaveList 


SIS 
$19 
$1A 
$1B 
UC 

$in 

$1E 
SIF 
S20 

S20  +  B  *  AWaveCount 


Figure  11-9.     The  ADSR  Envelope  for  a  Soi,ind 


amplitude 


attack   d»cay  sustain 


lime 


fades  away;  fof  other  types  of  instnimeiils,  such  as  an  organ,  there  is  little  change 
in  volume  tiurijig  the  sustain  stage.  The  find  stage  is  the  release  stage,  which 
cnrrespunds  lo  th<?  complf  te  release  of  key.  For  most  instruments,  the  Vulume 
drops  ufF  rapidly  during  the  release  stage. 

The  meaiiing  of  each  parameter  in  an  instrument  definition  is  discussed  helow. 
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ADSR_Envehpe.  Tin-  ADSR_Eiivpbpe  field  is  madL-  up  of  eight  3-liyte  entries 
tlitil  define  the  shape  of  the  ADSR  envelope  at  eight  ciiiFercnt  stages; 

•  Stag^e  1:  volume  1  (hytej,  intrrement  1  (wnrd) 

•  Stage  2:  volume  2  (bytej.  increment  2  (word} 

•  Stage  3:  volume  3  (tiyte),  jncremeril  3  (word) 

•  Stage  4:  volume  4  (byte),  increment  4  (wordj 
■  Stage  5:  volume  5  (byte),  mcremeiit  5  (word) 

•  Stage  6:  volume  6  (byte),  increment  6  [word) 
"  Stape  7:  volume  7  (byte).  Ineremcnt  7  (word) 
"  Stage  8:  volume  8  (byte)^  int'rement  8  (word) 

In  each  threesome,  the  first  byte  is  u  volume  (0  to  127)  and  the  following  word  is 
an  Increment.  Ftn-  a  given  staRe.  the  incmncnt  value  indiLate.',  how  fast  the  volume 
is  to  fliiinge  from  whfit  it  was  in  the^  previous  stage  to  what  it  is  in  the  current  ^tage. 
That  is,  the  inerement  sets  the  slope  of  the  ADSR  envelope  for  a  particular  time 
interval. 

The  lime  needed  to  slope  up  (or  duwnj  to  the  volume  ut  a  particular  stage  esn 
be  calculated  from  the  following  formula: 

time  =  ah?i(]iu.t  volume  —  new  VQluioe)  *  £.36 
increment  *  update  rate 

where  abs  ineaijs  absohite  vulue  and  the  update  rate  is  the  one  passed  to  NSStartup. 

BeleaseSeament.  Thr-  Bel  ease  Seiiiiieut  field  iif  the  instrument  dpfinftfon  contains 
the  number  iminus  one)  of  the  ADSK.Envclope  stage  to  wtiith  the  Note  Synthesizer 
goes  when  the  nnte  is  released  {a  note  is  n-lcased  when  yuu  tall  NoteOff).  In  most 
cases,  the  iuitrumifnt  will  release  to  a  zcru  volume  in  one  stage,  so  the  volume  byte 
for  this  stage  wdl  be  0. 

Priorittflntrremenl.  This  field  contains  the  numhct-  that  will  be  iuhtracted  from 
the  generator  priority  w  lien  the  note  reaehe_s  the  sustain  segment  If  vou  allocate 
all  generators  at  the  same  priority,  this  will  force  older  notes  to  he  stolen  first,  whicli 
is  usually  what  you  want  to  happen. 

PilchBeiulRaiige.  'tliis  field  Hmtains  the  numher  of  MIDI  .liemitoues  the  pitch  of 
the  wm  eform  will  be  raised  when  the  pitchwheel  reaehes  127.  PitchBendRanRe  can 
be  1.  2.  or  4. 
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VafraiuDeplh.  This  field  t-uiUams  the  ainplitudc  of  a  Iriiinglc-shaped  wave  thai 
mnduSates  thr  main  WLivi-furin  for  the  note.  It  tan  ran,iie  IroiVi  0  (no  vibrato)  to  127. 

VibratuSpeed.  This  fiokl  L'iratrols  the  frequfnty  of  thr  vibrato  modulillion  and  c;iii 
ran^t  Iruni  0  to  255.  The  efxaH  iVc-ciueiiCv  d*-peiids  on  the  updale  rale  passed  to 
NSStiLrtup- 

AWaveCount.     AVVaveComH  is  a  Ijy  tw  t-ontiiiiiiiie  the  rumibrr  of  wave  definitions 
(I  to  2.a5)  in  tlie  AVVaveList  field  Ibr  tlic  fir^t  oscillator  used  b>  the  generator. 

BWaceCQunt.     BWavcCoiint  is  a  byte  cnntaiiiiiis  thi-  luinbi-r  «1  wjvp  definitions 
tl  to  2.>'?)  in  the  BWaveList  fieiti  fur  ihc  setjond  o.seillator  usetl  by  the  generator. 

AWaveList  and  BWaveLisf.  There  ar<-  two  wavdists,  one  for  each  o.stiIlator  in  the 
genpra[c)r  osed  t!i  pUv  a  note.  Using  wavelists.  you  can  xssiKn  difTercnt  waveforms 
to  difFprcnt  semitone  ranpe^.,  Lhaii^f  !he  pitch  sliRhily.  and  ^et  the  POC  ope ratinp 
inodc-  All  the  waveforms  must  be  loaded  into  DOC  liAM  before  the  note  is  played. 
Each  entr\'  in  a  wavt  li&t  bai  the  inllowins  format; 

TnpKey  (byte^        Semitone  limit 

WaveAddrcss      (byte)        DOC  Address  value 
WaveSize  {byte)        DOC  Waveiorm  value 

Dt>CMode  (byte)       DO<:  Oscillalnr  Control  value 

RelPitth  (word)       Pitch  tuning  Tactor 

TopKeu-  TtjpKey  represents  the  hisbest  MIDI  semitone  to  whidi  the  waveform 
dcscribtd  l>y  the  wavehst  applies,  The  lowest  applicable  semitone  is  the  TopKey 
value  for  the  previous  wavelisl  entry  plus  L  Wavelist  entries  must  be  in  increasinj; 
TopKcy  order,  anJ  the  TopKey  for  the  laat  entry  musi  be  127  (tlie  hiyhebt  MIDI 
semitone  alluwed). 

WamAdtifesis.  Thl-s  value  iiidieates  the  starting  page  of  the  waveform  in  the  DOC 
RAM  area.  The  Note  Synthesizer  puts  this  value  direetly  into  the  DOC  Address 
register. 

WaveSis^e.  This  code  represents  the  Address  Table  and  Resolution  for  the  DOC 
oiitillator,  The  Note  Synthesizer  store.s  this  value  m  the  DOC  Wuvelorm  register. 

DOCMode.  This  viiluc  plated  direetly  in  the  Oscillator  Control  register.  As 
mentioned  rarlier  in  this  eliapter.  this  register  LiHilrnls  the  output  channel  number, 
ostilktor  interrupts,  operating  jnode,  itud  haltypky  status.  When  usiiip  the  \ote 
Synthesizer,  you  normally  want  the  Qsciilator  to  be  runnins  in  free-rnn  mode  in 
ehannel  #0  with  no  interrupts,  so  the  DOCIMode  byte  is  S<H),  It  is  also  rammon  to 
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ha\i;  t\w  Firwl  !iSLill;itiir  mii  in  swup  modi"  f.SOlil  for  thr  :iMark,  sn  that  it  will  swap 
to  the  Nt'cond  oscillator  operating  in  iVt-i-'-run  mode  lor  tht'  rest  nt'  the  notft.  En  this 
-sjtu;i,tiQii,  the  setcjiid  osciLliitur  initially  liiis  n  D<)<JM<idf  of  $01  (frtc-run,  biil  halted); 
its  halt  bit  is  cletired  au tnmiAtiLdlly  by  the  DOC  when  thv  swap  takes  place- 

Ri'lPitih.  Tliis  nuinlier  is  usA^ii  tu  thange  tlif  pitth  of  a  wa.v<'fonii  in  4  minor  way. 
Tlif  low-orilf  r  hytf  is  in  units  of  1/256  Keniitoiie^  the  hish-Drder  hytt*  is  \i  twn's- 
tDinplfniciit  signed  iioinlirr  rfprL-senlin;^  wholt  st- initoiit's.  llt=lPikh  in  ntinnally  sf t 
toO. 

Turning  off  £t  Nole 

V\'}i(.'ii  it  is  linif  to  tiiili  nff  a  note,  tall  the  NoteOff  (unttioii.  This  fortes  the  Nute 
S>ntKt?siZLT  til  fjo  directly  to  the  releasr  stage  in  tlie  note  s  AUSR  envelope.  For 
most  iiistrnint'iits,  this  eausps  the  \oluitic  of  the  note  to  tiitiekJy  decay  to  a  zero 
Ifvel,  When  ihiK  huppen^,  no  tntire  ^nniid  is  hearct,  the  peiieriUor  used  for  the  note 
\s  uutoKuitiLiilK  deallcttnted,  and  its  priin  ity  is  set  to  0. 
Here  is  htm  to  tall  MntcOff: 

PushUnriJ  GenHum  jCenerator  number  for  Itie  note 

PuBhWo*Ti   Bemilon^  iSemitane    i/aiue    for    t  fie  note 

_HDteDf f 

II  yoii  want  to  turn  iiR  all  iwtts  at  o:ice.  use  AllNotesOff,  It  requires  no  parameters. 

The  Note  Synthesizer  also  has  a  function  for  explieitly  deallo'catiag  a  generator — 
DeallocGen; 

PuShUlord  GeTiNani  igererator  number 

_Defl 1 J  ocGen 

TIlis  luzietion  .nets  thf  priority  of  the  generator  to  0  and  li:±lls  its  two  osedlators.  Yiiu 
should  not  need  to  ust'  DcalloLGcn.  heiaiise  tKe  Note  Synthesizer  calls  it  fnr  you 
ijutomatieally  when  the  note  volume  goes  to  0. 

Shultidg  Down  the  Note  Synthesizf^r 

When  you  are  finished  with  the  \nte  Synthesizer,  call  N'SShiitDown  (no  paranie- 
ters).  It  automatically  turns  off  all  jijeneratoics  used  by  the  Note  Syothesizer.  so  there 
is  no  need  to  eall  AllNutesOff  or  DcallocGen  first. 

PLAYING  A  SONG 

The  SONG  pr(>^r!ini  in  listing;  IJ-4  shows  Iiom  to  use  the  Nute  Synthesizer  to  play 
the  seri<?s  ot  notes  th^t  m^Vf  np  a  sonj?.  Notes  are  defined  fof  two  distinel  musieal 
Cracks,  and  the  prnj^rara  combine's  these  tracks  to  pliiy  the  soni^;.  In  the  example. 
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the  same  instrumeril  and  wavipform  is  used  for  each  track,  bi.it  with  a  little  extra 
effort  you  could  a-isign  a  difft-jrent  instrument  and  waveform  to  each  track. 

Each  (rack  in  the  sonji  is  dt-fiiied  by  a  Stries  of  four-word  note  recnrAs^.  each  of 
which  dcfiiifs  the  pitch  tif  a  nute,  its  i-oluiiie  iiiid  duration,  antl  the  time  interval 
between  the  start  of  the  note  and  the  start  ol  the  nest  note.  (Yhu  can  play  neveral 
Tiotf*;  at  the  samp  time  in  one  track  hv  specifying  a,  0  internal.}  The  ecid  of  the  Iratjk 
is  marked  hy  tour  consecutive  0  \\  or(l!i.  Here  is  tht  cxaet  format  of  a  note  record; 

•  MIDI  M-milone:  I)  lo  127 

•  MIDI  vdkime;  0  tu  127 

•  note  duration:  in  units  oi  1/30  scwnd 

•  note  internal:  in  Units  of  1/30  second 

Each  unit  of  ntite  duration  or  note  interval  i.'i  i/SOth  iif  a  second,  because  the  update 
rate  pas.^ed  tt)  XSStarlup  is  30  Hz.  If  you  use  a  difl'erent  rate,  you  must  change  the 
duration  Lwdes  acL'HDrdingily, 

Til  add  anolhtr  musin-al  track  to  the  SONCi  pnjgrara,  Rrst  increase  the  value  of 
TrackMax  by  1  and  place  a  pointer  to  the  track's  note  table  in  the  (rack  table  that 
fol]nw.«i  TrackMiLx.  [finallv,  insert  the  note  table  for  the  track  and  termijiate  it  with 
four  zero  words.  When  yoii  reassembU'  the  program,  the  new  track  will  be  pJayed 
with  all  the  others. 

The  portion  of  the  SONCi  proitirdm  that  does  most  of  the  work  is  the  Betiuencer 
subroulijie  II  is  called  at  the  update  rate  (3t>  times  per  secondl  and  is  lespoiisible 
for  keeping  track  of  the  status  of  ail  notes  being  played  and  for  turning  notes  on  and 
off  when  necessary. 

When  Sequencer  first  gets  control,  it  decrements  the  note  interval  counters  for 
each  track;  the,se  counters  were  (irif^inally  iel  equal  to  the  value  -stored  in  the  record 
for  the  last  note  played  in  each  track.  (Tlie  program  puts  Is  in  these  counters  when 
it  first  starts  up  to  fort^  the  first  notes  in  each  track  to  he  played  ri^ht  away.)  If  a 
counter  becomes  (1,  it  time  tu  pIli\'  the  next  note  in  the  track,  so  Sequencer  calls 
the  NextNote  subroutine  ti>  net  tlie  next  note  record  IVoin  the  lii^t.  It  tben  turns  the 
note  on  by  allocating  a  y;enerator  with  AllocGeii  and  then  calling  NoteOn.  It  also 
adds  H  lo  the  track's  lujte  pointifr  so  that  it  points  to  the  next  note  record. 

.^ter  Sequencer  turns  im  dn\  notes  Ihiit  are  ready  to  be  played,  it  decrements 
the  duration  counters  for  all  generators  that  are  still  plac  ing  notes.  These  counters 
were  initialized  when  the  note  wm  first  turned  on.  If  a  counter  becomes  0.  it  calls 
XnteOff  (o  release  the  note.  Tlie  generator  is  automatically  deallocated  when  the 
volume  goes  to  0, 


P/ayirtg  a  Sang  415 


REFERENCE  SECTION 

Table  Rll-li    The  Major  Funtlions  in  the  Sound  Manager  Tool  Set  (S08J 


Function 

Stack 

Dencriation  of 

Furtction  Name 

Number 

Pai-amL'tvr 

FFG  eneralorStatua 

$11 

result  {W) 

Generator  status  word 

CeuNum  (W) 

Generator  number 

FFSountlDnneS  tatus 

$14 

rcsidl  (W) 

0  ^  playing/^FFFF  =  stopped 

CeiiNum  (W) 

Generator  number 

FFSoundStatus 

SIO 

result  (W) 

Generator  status  word 

FFStartSound 

SOE 

GenMode  (W) 

Generati^r  (high),  mode  (low) 

ParamBlrwk  (L) 

Ptr  to  parameter  block 

FFStopSound 

$0F 

C  en  Mask  (W) 

Generator  mask 

GetSoundVoluniE^ 

SOC 

result  (W) 

Volume  settLiig 

GcnNutn  (W) 

Generator  number 

GetTableAddress 

SOB 

resuk  {L) 

Ptr  to  low-level  DOC  table 

ReadRamBlwk 

SOA 

DestPtr  (L) 

Ptr  to  destination  address 

DOCStart  (W) 

Starting  address  jo  DOC  RAM 

Count  (W) 

Size  of  Wiive  tn  read 

Set  Sound  M  IRQ  V 

$12 

MasterlRQV  (L) 

Ptr  to  new  Aound  IRQ  haadler 

SetSoundVohinie 

SOD 

VolSetting  [WJ 

Volume  level 

GenNum  {W) 

Generator  number 

SetUsL-rSoiiridtHgV 

$13 

residt  (L) 

Old  user  IRQ  handler 

NewIRQV  [L) 

Ptr  tQ  new  user  IRQ  handler 

SqundShutDtm-n 

$03 

loQ  parameters] 

Sound  Startup 

$02 

LJPAddr  (W) 

Address  of"  1  page  in  bimk  0 

WriteRainBluck 

$09 

SourtePtr  (L) 

Ptr  tu  start  of  data 

DOCStart  (W) 

StarHng  address  in  DOC  RAM 

Count  (W) 

Size  of  wave  to  write 

Sound  and  \tusic 


Table  Rll-2:     Sound  Manager  Error  Codes 


Error 
Code 


$0810 
SOS  11 

mn 

$0813 
£0814 
S0815 
$0817 
$0818 


Description  of  Error  Confiition 


The  system  does  not  contain  a  DOC  chip. 

The  spiccified  DOC  address  is  invalid. 

The  Sound  Manager  has  nni  heen  initialized. 

The  generator  number  is  invalid. 

The  synthe:iii£er  mode  is  invalid. 

The  Renerator  is  busy. 

Thif  master  IBQ  vcLlor  has  not  been  assigned. 
The  Sound  Manager  has  already  heen  started  up. 


The  Snund  Manager  can  bIm  return  Meifvor^'  Mui»K«r  and  ProDOS  16  error  codes. 


Table  Rll-3;     The  Miijnr  Functions  in  the  Note  Syntheiizer  Tool  Set  ($19) 


VunCtioti 
Name 

AllNofesOff 
AllocGen 


DeaUocGen 
NoteOff 

NoteOn 


Function 
Number 


Stack 

ParaineteJ^ 


$0D  [no  parameters] 

S09  result  (W) 

CenPriority  (W) 
SOA  GenNum  [W) 

$0C  GenNum  (W) 

Semi  tone  (W) 
SUB  GenNum  (W) 

Semitone  (W) 
Volume  (W) 
Inst  rumen  tPtr  (L) 


IJescriptiort  of 
Faratnster 


Generator  number 
allocated 

Generator  prinrity 
Ceneratoir  number 
Generator  number 
MIDI  semitone 
Generator  number 
MIDI  semitone 
Volibme 

Ftr  tu  instrument  definition 
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Function 
\'ame  

NSShutDown 
Startup 


Functiuti 
$02 


Slack 


[nil  parameters] 
UpdatrRatc  (W) 
UserUpdate  (LJ 


DeicripUoii  of 
Parameter 


Update  rate  code 
Ptr  to  update  handler 


Table  S11-4e    Note  Synthesizer  Error  Codi.-. 


Error 

Cftlr 

SI  90 1 
$1902 
1^1921 
$1922 
S1923 
$1924 


Description  of  Error  Condition 


The  Note  Synthesizer  Ims  already  been  jnitialiiricd, 
The  Sound  Manager  has  not  hecn  initialized. 
No  generatur^^  are  avudiihltf. 
liiMalid  generator  number. 

The  Note  Synthesizer  has  not  been  initialized. 
The  generator  is  already  being  used, 


Table  Rll-5;     Useftd  Functions  in  the  Mistellaneous  Tool  Set  ($03) 


Function  Nairw 


Fii  nc'if"! 
.Vii  m/wr 


Faratneters 


Dfscripiioii  of 
Parameter 


SysBecp 


$2C 


[no  parameters] 
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Listing  1 1-1;     Ocatiilfi  Simple  WavrlorniS 


[a)  Creating  and  loading  a  sine 


Loads  1 ne 


flNDP 

PuahPtr  WavtForm 
PLjahWord  *iGa<lll 
PushWord  'tlOO 
_UriteiiamBlock 

RT5 


Pomter   to  vfaveform 
Starting  DDC  address 
Mumtier   ai  bytes 


This    15  a   5  L  re  wa ve . 
the   formula  V  127 
PI    -  3.14156, 


The  values  were  calcLilated  from 
■  5IN{X   '  2  •  PI/2be)   '   128  where 


WaveFor  m 


DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 


II 

n 
n 
11 
11 
11 
11 
[  1 
II 
11 
It 
n 
II 
11 
11 


I  177 

'218 
*£45 

'21S 
f  1  77 
'  12B 
"79, 
'  38, 
'11, 
'1  .1 
'11, 
'3S. 
*79, 


ANOP 

.1 31 ,1 34 
,  t  79, 1 82 
,220 ,222 

.25S  .255 
,241  ,?43 
,216,?13 
,174,171 
,1  25  .12? 
77,74  ,71 
3G  , 34 , 32 
1 0 ,8,7,£ 

.1,1,2,2 
12,13,15 
40  .  43 , 45 


137 
18S 
324 
249 

,2^1 


1 40,144 ,147,150,153, 
18B,191 .193,195,199, 
.225, 228, 230, 23?, 234, 
,250  ,250  ,251  ,252,253, 
,254,254,254,253,253, 
,240.239,237,235.234 


1SG, 159,162, 165. 168, 171 
20  1  ,204  ,2QG,2C9,21 1  .21 3 
235, 237, 239, 24t], 241  ,243 
253.254,254,254.255.255 
252,251 .250.250,249,248 
232,230.228,225,224.222 
21  1  ,209,205,  204  >2[J1  .199,195,193.191  ,188,185,182 
168  165,162 ,159,156.153.150 ,147,144,140 ,137,134 
11  9,116,112,1  [39, 106,  1  03, 1  00, 97,  94,  91  .58,85,32' 
58. G5, 63, 60, 57, 55  , 52. 50 ,47,45,43,40  ' 
30,23,25,24  ,22,21  ,19,17, 16,15,1 3.12' 

6,5.4.3,3,2,2,2,1,1,1' 
2,3,3,4,5,5.6,7,8,10' 

16,17,19,21 ,22,24.25.28,30 ,32,34 ,36' 
47,  50.52,55.  57, 6[),63,ES,GS,71  ,74  ,77' 
91  ,9<l  ,97,  100,5  C  3,1  Oe.  109. 11  2, 11  6, 11  9, 122, 125' 


.  1  74  ' 
,215' 
,244' 
,255' 
,246' 
,,220  ' 
.  1  79' 
.131  ' 


(bl  Creating,  and  laadirg  a  Irkangle  wave: 
LpadTnarg  ANDP 


SEP 

«f  20 

LDHQA 

OFF 

LDX 

'0 

LDA 

«I4D 

STA 

W3 VP  Form , K 

INC 

A 

INX 

CPX 

*S80 

BHE 

Pu  tUlau?  1 

^8-bit  accumulator 

;  start  of  triangle 
Ifflove  up 
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STfl 
DEC 
INK 
CPX 


>fS1  00 
PutUave? 


imowe  down 


REP 
LDN&A 


QFF 


;I6-bit  accumulator 


PushPtj-  WawtFoi'Jn 
PuahUord  ^lOOOO 
PushWofd  'HQQ 


RTS 

WaueForm  DE 


iPointer   Id  waveform 
i  Slar  t  Ing,  DDC  address 
jNumber  of  bytes 


Listins  U-S;     Thp  CONVERTER  Program 


*  This  program  ahowa  hpw  [q  digitize  an   incoming  * 

*  analog    signal    through   the  Enaoniq  Dac  » 


KEEP 
hCtJPY 

DcrefLoc  GEQU 
TflbJePtr  GEQU 
Sample  GfQU 

Con\;erler  START 
U5[MG 


ANALOG 
fiNALa&.MflC 

SOO 

$08 


;Uged  for  der     t  r  BTi  c  i  ng  handl 
iPoiTiter    to   lou-ievel  table 
;Pointer    to  start   of  buffei' 


PHK 

f-E  iPfogram  bank    ■   data  bank 

JSR  Startup  ;5tart   up  the  taol^ 

Allocate  a  32K  buffer   far    the  samples; 

;Space  for   result  (handle) 


PHA 

PHA 

PLishLong  JftBCQd 
PushWcrd  MyJD 
PyshWord  *tCOO0 
PuahLoTig  *iO0 
.HewHondle 
PopLong  DerefLoc 


iRcaervc  32K  block 

j ID  tag  far  memory  block 

jLockedi,  fixed 

;    [no  mtanirgl 
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LDfl  ,C««v«rl  handle  poirter 

STft  Sample 

LDY  *2 

LpA  t  Der ef Loc  ]  ,  Y 

STfl  Sflmpls*? 

Get   addr«s  of  ^..broLitine  tabic; 

ispsce    for  result 

PHA 

PopLong  TablePtr 

T-h..lr  iiddre^*         the  DOC   read  idbrouline  Ifirst 
'.'%h,'?;:i:>     r..=  operand  of   .K.  J5L  >.,Ua....n, 

LDft  ITablePlr^ 

gtfl  J3L_Patch*1 

LDY  " 

LDft  [ToblePtf]  .Y 

ETA  JSL_PaUh*2 

JSR  DoSampl=  ;5lart  sampling 

;    [ir5trt  code  here  to  "ve  sample  to  di^t,   etc  .  1 

JMP  ShutDown  iFirish  Lip 

This    aubroutlTiE  aamplea   the  analog   input    line  until 
The  .ample  .w.         ret.r.ed         the  V  register. 


DnSarnple 

AHOP 

SEP 

'(SO 

□  FF 

iB-b it  accumLilatcr 

GelSamp le 

LDY 
PHY 

;  Ini  t  lal  i buffer 
l5flvp  polntC 

painter 

LD)( 

jfinalog-to-Dig^'^*'^ 

regi  5  ter 

;    Ihe  pragrarti; 

JSL.Patch     JSL  1123^56  1^"-^  -9-^" 

PLY  ;&ct  poirler 


Bfi/crence  Section 


STA 


[Sample] , Y 


;Save   the   sample   in  buffer' 


I  NY 
CPY 
BEQ 


;Eump  bluffer  pointer 
;flt  32K  limit? 
t  *f*9  ,   So  branch 


;    Use  B  delay   loop    Ijie   this   to  adjust    the   sampling  rate. 

;   A  vaiiifr  of   175  for    X  givea  a  rate  af  about    lOOO   aamp  1  e  5  /  second . 


LDX 

^r47S 

;Delsy  counter 

De  lay 

DEM 

BME 

Delay 

;    Chec  k 

iseyboard 

for  ESC  (see 

chapter  12): 

LOA 

lEOCQOO 

; Check    t  eyboard 

BPL 

Ce  t  Samp  1 c 

^Branch   if   nothing  there 

STfl 

IE0CO1 0 

;C][i?er   keyboard  almbe 

CMP 

'%5B 

;E5c'' 

BNE 

Ge  t  Sampl e 

;HOj   so  get  next  sample 

REP 

;Back    to  16-bit  accunmlator 

RT3 

END 

■  start   up   the   standard   tool   9et5  * 

Startup  STftRT 

USING  GlobalDatfl 

_TLStarliip 
_MTS  tar  1  up 

PHfi 

_MMS  t  □  r  t  Lip 
PLfi 

5Tfl  MylD 

*   Gtl   one  page    in-  bank    IDO    for  SoundSlartLip: 

PHA  ;SpflCt  for  result  (handle) 
PHfi 

PushLong  '$100  jReserve    one  page 

PushWord  My  1 D  J  ID  tag  for  memory  block 

PushWord  ^SCQOS  ;Locfced,   aligredf  fixed 

PushLong  'iOO  m  bank  fOO 

NewHand 1 e 
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1  Oe reference   the  handles 


PopLong  DerefLoc 

LDA  [DerefLocl  !&et   direct  page  addresa 

PHA  ;Pjah  direct  page  address 

_Soan(i5lflrtLip  iStart   tip  the  Sound  Manager 

RTS 


i  Shut  down  all  the  tool  sets 
;  and  le^v^  the  application: 

ShutDown  ENTftY 

_5oLindShLitDQwn 

PushUord  nyiD 
_nMShutDowTi 

_MTShutDawn 
_TLShLjtDQwn 

_Ouit  QultParma 

Qu  1  tParma     DC  H • Q ' 

DC  I2'0' 

END 


GlobalData  DATA 

MylD  DS  2  ipro^ram   ID  tag 

END 

Listing  11-3:  An  Exaniplr  tiFan  IiLstriinit^nt  Dr-pnition  _ 
Inatrument  flUDP 


DC 

11  1 

'  127  .Q  .1 27' 

;Sharp  attack   to  man  uo 

lume 

DC 

1 1  ' 

'  12D  .20  ,  1  ' 

;Slow  decay 

DC 

1 1  ' 

1 120 ,0,0' 

■.^LiataiD  at   same  level 

DC 

[1 

10,0,110' 

;  Re  lea  se  to  ;er o 

DC 

11 

'0,0  ,D* 

jtynused  stagel 

DC 

n 

■  0  .  D  ,  0  1 

; [unused  stage] 

DC 

1 1 

'0,0,0' 

jLunLLsed  atage] 

DC 

11 

'0.0.0' 

;[ unused  5 tage 1 

DC 

11 

•3' 

;Relea5e  stage  number 

DC 

11 

'32' 

^Priority  reduction  at 

sustain 

DC 

n 

igr 

;Pi  tchberid 
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AUaveL 1  St 


BWaveL I  a  t 


DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 


90' 


D* 
1  • 
1  ' 

1  27  I 
1  '*00' 
1  '  0  ' 
1  'S' 

T  M27' 
1  I  tOl  ' 
1  '0' 
I'll 
2101 


Listing  l!-4i     Tlw  SONG  Pmgriiiii 


;VibratD  depth 
i [spare] 

;Nii(nber  of  cTitries  ip  AUavcHsl 
jNumbcr  of  ETilnes  in  BHaveli^t 
J  TopKey 

iStarta  at  page  100  in  DDC  RAM' 
iWaveform  regi5lef:    ore  page 
;Mode:    swgp    to   B.  piayipg 
;  No  pitch  eh.aTige 
;  TopKey 

iStarts  at  page   101    in  DOC  BflM 
:Waveform  regLster;    out  page 
^Mode:    free-run,  halted 
iMo  pitch  change 


■  This  program  ahows  how  to  construct  ^  simple 
*     tunc  uairg  the  Note  5yTitht5i?er, 


NotePtr 
1  (1 1  erwa  1 

Song 


KEEP 
MCOPY 

START 
USING 

US  ]N(5 
US3MG 

PHK 
PLB 

T&C 
STfi 

JSK 

JSR 


SQHG 
SONG. MAC 

to 

S20 


GlobalDatfl 

TheN  E>  t  e5 
I  ns  t  r-ufnen  t 


MyDP 
Startup 
Mfl.k  eW-aue 


I Po inters  to  each  note  track 
itLme  urtll   ne»:t   note  begirrs 


;Progr^m  bank  •>  data  bank 
;5flve  current   dir&ct  page 

^Load  wave   into  DDC  RAM  area 


;   Get    the  Note  Synthesi2er   up  and  rurning: 

3EI  !Nq  inlerruptHuntilwe'raready 


PushWord  075 

Pus  hPl  r  Bequencer 

_HSS  tar  t  up 


-,3  0  Hi  update  rate 
;  I  nter  rup  t  haTidler 
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Hhtb    IB    the  main   program  loop 


KeyUait         PRINTLH   'Press  any  key  to  Hart   the  5org   (ESC  to  concei.):' 
PHfl 

PuahWord  *0  ;C   -  no  echo 

_RcadChar 

PLfl 


AND  'S7F 
CMP  *51B 

gEQ  ShutDoun 


Convert   to  flSCt  t 
ESC  pressed? 
Ves ,    50  ba 1 1  out 


i    Initialize   the  pointers    Id   the  aound  tables  and  ftit 

1    things   up  5o  that   the  firsl   rote   in  each  track  ia 

;   played  right  awayt 

LDK  *□ 

DoTable^       LDA  Trac  IcMax'^S ,  X  jTraiiBfer    track   pointer    lo  d,p. 

STfl  NatePtr.j; 
LDA  TrackMaxM^K 
5TA  NQleP[r»?,X 


STA  lnter'val,)(  ;(CaLSES  Ist   note  to  ha  play*d| 

INK  jMovetorejclenlry 

INX 
INK 


INY 

CPY  Tractnaa 
BNE  DoTablcs 


; Done  al 1  track  a? 
;Hci,   so  branch 


CLI  ;Allow  Bynthesizer  interruptsl 

BRL  KeyWalt 


i  Shut  down  all  the  tool  seta 
:   and   leave   tht  application: 

ShutDoujn       _HSSh  Lit  Down 

_Text  Shu  tDsun 
_SoundShutDown 
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PuahWord  My[D 
_l1MShutDown 

_MT5hu  tDa*n 
.TLShulDown 

_Qu It       Qu 1 t  Parma 

Qui tfarma     DC  H " D  * 

DC  lE'O' 


END 


•  This   SLibrout  I  rre  gets  control   after  a  Note  Synt  hea  i  ze  r  < 

•  interrLipt.    Inten-iipta  occur   30   1  i  mes  /  sec  ond  .  i 

Sequercer  START 

US  I N&  I ra  t  rument 

USJNO  GlobalData 

U$]HG  TheHutaa 


PHB 
PHK 
PLB 

PHD 
IDA 
TCD 


MyDP 


;A11dw  abaolLile  addressirg 
^Switch   Ic  appi  1  ca  t  1  f^n  ■  5  d*p. 


J   Ctiecl    Id   see   If   it's  time  to  play  the  neil  note; 


DoTrac* 


LDX 

DEC 

PHX 
PLX 


1  r  1  ervB 1 
NeictTracIt 


Ne«tMot= 


;Rcduce   time  to  next  note 

;Branch   if   not    time   to  play  next  tioI 


^Get    next  note 


NeittTract:  TDC 

ADC 
TCD 


#4 


;Keep  the  d.p.  i.n  step  with 
}    the  current    t  rack  . 


INI! 

CPX 


Trac  kriflK 
DoTrac  t 


;Done  a\ 1  tracts? 
iNo,    so  bradch 
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J  Turn  off  ^11  geTieratora  whose  notes  are  done: 


#13-2 

Du ra  1 1  ori ,  K 
NexlG*n 

D«i  ration, X 
Next&En 


Ger^«ra  t  o  r  .  K 
Semi  tone , X 


LDX 
LDfl 

BEQ 

DEC 
BME 

PHX 

LDA 
PHA 
LDfl 
PHA 

_NateOf f 

PLX 

DEX 
DEX 
0PL 

PLD 
PLB 
RTL 


J  Get  IhE  next  note  in  the  note 
NextNote 


; 1 5  thi^  note  playing? 

;No,    *o  branch 

;Rcduce  diiration  couTiter 
^Branch   if  more  to  come 

jDon^t    destroy  X 


Mexteen 


GenChec  I: 


iTurn  off  the  note 
;  Restore  K 

;Move  ttt  next  generator 


I  Re store  direct  page 
ifteatore  (tflta  bank 


tables 


LDfi 
RT5 


[NolcPtr] 
GetCen 


GetOen 


PHA 

PushWord  *127 
_fl 1 1 ocGen 

PHfl 
PHfl 


flSL 
TAX 

PLfl 
STA 

LDA 
STA 

LDY 
LDA 
STA 


Genera  tor , K 

[NotePtr  J 
S.em  I  tone  ,  K 

[NotePtr  ]  ,V 
Ou  ra  t  1  o  n  ,  X 


jGet    next  aemltone 
jBranch.   if   note  defmpd 


jSpace  for  result 
iGeneralor  pricrily 
;Allt>cate  a  generator 
;Gel   generator  number 
;(kpep  a  copy  on  stack) 
;  (  .  .  .    and   another  ]r 

;x2  for  array  pD^ition 


;Stiire  generator  number 


jStore  note  Bemitane 


;5tore  TiQte  durati-on 


Reference  Section 


LDV 

LDfl 

[NotePtrl ,Y 

STfl 

1  n  li^rvfl  1 

;    Sound  th 

e   rotp  by  callirq  Not 

;   number   15  alread 

y    on  atdckj; 

LDft 

[NotePtr J 

PHA 

LDV 

LDA 

[NolcPtr ] , V 

PHfi 

Pu^hPtr- 

J  TI5  t  rumen  t 

_No  tetJn 

•   Bump  the 

pointer 

to    the  neitt 

CLC 

LDfl 

HotePtr 

ADC 

STfl 

HotePtr 

LDA 

1  Fi  [  p  r  1 

BEQ 

NexlHote 

PTS 

Generator 

DS 

11-2 

S#m 1 1  one 

DS 

1  4«2 

rat  1  on 

DS 

1 1*2 

END 

;5ldre  time  !□  next  rote 


;5ern  1  tone 


Vo 1 ume 

I  r  st  rument 

Start   soufidiTig  the  note 


;fldd  giie  of  ngte  record 


;Deiay  before   H'ex\  note? 

iNoi    so  get   next    note   right  ni 


jGeneratgrs  used  by  actii^e  notes 
;Semitone9  used  by  active  notes 
jDurationa  of  active  notes 


*  Th  1 5  data  segmeTi  t  def  me^  the  notes  • 

•  for    the   tune  we  will  play.  • 

TheNctea  DflTfi 

;   The'se  are   the  MIDt    codes  for  semitones: 

o5  EQU  S4  ;Qctave  5  base 

EQU  9G  iDctave  &  base 

!    Semitone  offaeta   from  the  start   of  each  octave: 

C  IQU  0 

Cs  LQU  t 

D  EOU  2 

Da  EQU  3 
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E 

EQU 

A 

F 

EQU 

S 

Fa 

EflU 

0 

EQU 

7 

Ga 

EOU 

e 

A 

EQU 

Aa 

EQU 

1  D 

E 

EQU 

1 1 

i  Th 1 5  a 

table  of 

pointers   tc  each 

mu^ic   t rac I  : 

TrackPlan 

DC 

12'2' 

; Number  of  I rac  t  a 

DC 

H 'Track  1  ■ 

i  Pgi Titer   to  track 

DC 

H 'Tracts' 

;  Pa  L  n t er    to  tract 

1  Here  are  the  tidIe  de f  l  n 1 1  ioti5  ■   Each  is  nnade  up 

;  of  fOLjr-  words  describincj  the  aetnitone,  volume, 

-,  duratio:!,  and  the  inter val  until   the  n&xt  note 

',  ft  zero  semitone  mar1:9   the  end  of  the  list. 

;   This   IS   the  definition  for    "Happy  Birthday": 

Trackl  ANDP 


tfl  £QU  127  \Melody  volume 

DC  I 'a^rC.vl  i4,4' 

DC  I 'fl5  +  C,v1  .t.'fl' 

DC  1 'o5*PvVl ,e,S" 

DC  I'a5*C,v1  ,B,e' 

DC  I 'o5'F>v1 ,8,6' 

DC  I  'dS'E.vI 

DC  I  'o5*c.v^ 

DC  I  'oS^Cvl  ,4,4' 

DC  I  'oiS'D.ul  ,8,8' 

DC  J 'ci5*C  ,«1  .8,3' 

DC  1  'oS'G.ijI  .8,3' 

DC  I'[i5*F,w1.15,15' 

DC  1'd5*C.u1.4,4> 

DC  I "05*0, w1  ,4,4' 

<  DC  I 'dB'C.vI ,e,8' 

DC  l'o5*A,uI ,S,B' 

DC  1  "  cS-tF  ,y  1  ,B  ,8' 

DC  I'oS'E.vl ,0,8' 

DC  1  idS'D,-/1  ,1S  ,15' 

DC  I  'o5'fls,u1  ,4,4' 

DC  I  '  oS'-As  ,w1  ,  4  ,  4  ' 

DC  I  ' q5'A  ,v1  , Q , B ' 
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DC  1 io5+F,v1 ,B,S' 

DC  I 'ob*G,i/1  ,B,8' 

DC  I 'oS+F  ,v1  ,15,15' 

DC  I'O.Q.O.Qi  ;Enid  of   note  table 

;   Tratk?  contains  the       compfl  ny  i  ng  chiords: 
Tract? 

„2  fIflU  127  ;Chard  wolume 

; (6a   noth  i  rg ) 


127 

DC 

1 1  £>5*F  ,0  .s.a' 

DC 

1  'o5*F  ,v2,24,0' 

DC 

1  1  oS'^fi  .v2  ,  21  ,0  ' 

DC 

DG 

]  'ti5*E,v?.23,D  ' 

DC 

1  'o5*As  .v2.£3,0' 

DC 

1  '  o6  +  C .v? . 33, £3' 

DC 

DC 

I 'oS*ft , v2 , 1 G . 0 ' 

DC 

I  'o6*C,v3  ,1G  JGi 

nc 

1  '  aS  +E  v2 . 8 , 0 ' 

DC 

DC 

DC 

1  'o5*F,v2,23,0' 

DC 

1  'oB^-A.va.aSiO' 

DC 

1 "oS+C,w£,23,23 

DC 

I iQb'F .v^.^A  ,0 ' 

DC 

DC 

]  'o6'C.v&,34,2'4 

DC 

I'oS*E,vE,31 .0' 

DC 

DC 

I  'oG'C.vS.SI  ,31 

DC 

T  1g6*F  ,v2.1G,0' 

DC 

DC 

1  '.ob'CiJ?  JS,1G 

PC 

1  'o5'E,w2,a.Q' 

DC 

DC 

r ' oS»C , v2 ,8,3' 
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DC  l'oStF,v2,15.D' 

DC  T '  o5*A  .v2 ,15,0' 

DC  ['oe*C,v2,l5,15' 

■DC  I'OiO.O.Q'  ;  Enijofnotftlabie 

END 


This  data  defines  the  ms  IrumeTil  >^hich 
15  kiaed 


Nave? 


the  sotig- 

DATA 

dc 

n  '  *7F  ,0,6-)' 

do 

i1  '0, 0,102' 

dc 

l1  iO,0,D' 

<Jc 

i1  'O.O.O' 

dc 

11 f  D , 0  ,0  ' 

de 

l1 '0.0,0" 

dc 

11  '0,0  ,0' 

dc 

i1 1 D ,0  .0' 

dc 

il  '  1  ' 

dc 

11 '32' 

dc 

l1  tQ  - 

dc 

11  '0' 

dc 

i1  '0' 

dc 

il ' a' 

dc 

11 '  1 ' 

dc 

il '  1  ' 

dc 

il  1^27.0, a, 0,0,0 

dc 

Li  1  127,0  ,a  ,Q  .0  ,0 

END 

^Sharp  attocl' 
iSustaln  with  slciw  decay 
;    (the  other  sik  segments 
;     are  unused) 


iSegment   number   for  release 
;Generator  priority 
iPitch  berd  range 
;Vlhrato 

sVibralo  speed 
;  [unused] 

; Number  of  waue farms  for  a^c  *1 
;Humb*l'   of  waveforms    for   05C  '2 


.■  Lo^d  a  ludveform  into   the  first  pag^  of  DDC  RAM  • 
MakeWave  START 

;  Trarsfer   the  waveform  to  the  DUC  RAris 

Pu5hPtr     WaveForm         ;PointEr   to   tht  wave 
PushUord  ftOOOO  jbtartiTig  addrcBS    in  DDC  RAM 

Pu^hWard  'S10D  ;Traii5fer  one  page 

_Wri tefiamBloct  iDo  the  transfer! 

RT5 
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This   la  a  sine  wave.   The  values  were  calculated  from 
the  formula  V  -  B4'SIH(X  •   2-PI/25G)   '   1 ?8  "here 
PI    -    S-MISe.    The  isro  baseline   is  given  by   the  valiii<? 

WaveForm  flNDP 


S80. 


t  2B 
1  S2. 
1  73 
1S7. 
19? 
1B7, 
173, 
152, 


1  30 
1S1 
1  74 

192 

187 
172 
1S1  . 


12B.  1 .26  , 
1  04,1 02, 
63,52 ,81 
G9 ,gS,&S 

G9,G9, 7  0 
83,8-1.05 
1 04  ,1 05, 


131  , 
1S&, 
175  , 
18B  , 
192, 
186, 
171  , 
150  , 
125  , 
101, 
,B0, 
.67  , 
,G4, 
,71  . 
.66. 
1 


133, 
1  57, 
17G, 
1  89  , 
192. 
135, 
17C  , 
14B, 


1  3-1 
153 
177 
IS9 
192 
18<1 
1G9 
117 


1 122, 
79,78 ,77 

64  .G-s  .es 

72  ,72,73 
27,89,90 
1  OB, 1 09 , 


136,137.139. 
TGO, lei ,152, 
1 78 , t  79, 1 80 , 
190  ,190  ,!  90, 
1 92 , 1 91 , 191 , 
1  e-i ,  1  83  ,  ta£  , 
I G7 ,166,165. 
1  45  , 1  t-t  ,  1  42  , 
120,119,117. 
,9^,34,92,91 
,  76 , 75 , 74 ,73 
,GG.GS,G5,G5 
,&fi.G5,66,&G 
,74.75,76,77 
,91 ,92 ,91 ,95 
111,112,111, 


1 40 , 112,111 . 145,147, 
1 G4 , 165 , 1 GG . 167  , 1 69 , 
181  .laE,  133,184, 1B4 , 
1 91  , 1 91  ,191  , 1 92 , 1 92, 
191 .190,190, 19a, 189, 
1S1  ,180  ,1  79,1  78.  177  , 
164,152  ,1G1  ,  ISO  .158, 
110,133.1 37, 136,1 34  , 
116,114,112,111,109, 
, 90, 89,87,96.95, 84' 
.72.72.71 ,70,69' 
,64  ,61 ,G4 ,64 ,61 ' 
,GG. 67, 67.68,68' 
,78,79,30.81 ,82" 
.96,93,99,101 ,102' 
1  1 6, 1 1 7  ^ 1 1 9 , 1 20 , 1 22 , 


1 18  ,  1 
1  70  .1 

les  .1 


192  , 
189, 
1  76, 
157, 
133, 
1  OB  , 


50  , 1 51 ' 
71  ,172' 
86,187' 
92,192' 
88, IBS' 
1  74  I 
15-1' 
1  30- 
1  05' 


75; 

55, 
31  , 
OG, 


123,1 25,1261 


•  start   up    the  standard   tool    sets  ' 

Startup  STftRT 

USING  Glob^lDatfl 

DePefLoc       EQU         $0  -v^^d  for   dereferencing  handle 

_TLStar  tup 
_nTS t ar  t up 

PH:A 

_nt1Slflr  tup 
PLfl 

5Tfl  MylD 
PushPtr  ToolTabie 

_LoadToo 1  a  ; Load  the-  Note  Sequencer 

•  Get   one  page    ir,  bank    SQO   far  SoundSter  tup ; 

'^^'^  ;5pace  for   result  (handle! 
PHfl 

PuBhLong  #(100  iReserve  one  page 

PuahWord  flylD  ;  [D  tag   fcr  memory  b  1  oc  t 
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PiishWord  'tCQaS 
_NewHandl e 
;    Der  eference    the  halidlfi: 


PLA 

STA 
PLA 

STfl 


Deref Lgc 

Dpt  ef Lqc  f2 
[Dtf afLocl 


SoundSt^r  t  up 
_TeKt  Sta  rtup 
fits 


ToolTflblE  DC 
DC 

ClobalData  DATA 


121  1  ' 


MyDP 
My  ID 


DS 


ifltlfibutes  --  Igcled,  aligned,  fix^d 
:  ,  .  .    in   berlc  SOD 


;Get  direct  page  address 

jPush  direct  page  address 
iStarl   up  the  Sound  Manager 


;Qne  tool   set   to  load 


■jprggram's  direct  psgE 
iprogram  ID  tag 


END 
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CHAPTER  12 


Using  the  Text 
Tool  Set 


The  purpose  of  the  Tt^xt  Tnol  Set  (tool  set  12)  is  tia  give  programs  r  unning  in  65816 
iiativf  niodr  anvTA'hrrc  in  meinnn'  iin  easy  wiiy  lii  dirfit  diaractfr  i>iit|mt  ur  input 
operations  to  an  I/O  dtviLe  in  n  slot  or  port.  Doing  this  withnnt  the  Text  Too!  Set 
is  liwkwaid,  hccansc  thfst;  typei  t>f  I/O  tlfvices  must  Hp  uccPJiscd  while  in  emulation 
mock'  ami  vvhih'  the  tJila  biiiik  and  direct  paRO  registers  are  set  to  0.  (These 
rcstrietionN  stem  fniiii  the  need  to  iiialiiifain  (.nmpatihihty  with  lie  softwiire  and 
hardwire  J  The  runctions  in  the  Text  Tool  Set  late  care  of  saving  the  furreiil  mode 
and  rej;i.>iter!i,  switLliing  yun  !o  the  proper  ones  fni  thf  I^O  uptratiOn,  and  restoring 
the  nri^inal  values  on  exit. 

Tlie  lliree  inaiji  uses  of  the  Text  Tool  Set  are  to  rc&d  character  input  From  the 
keyboard  fwithout  using  the  Event  Manager),  to  display  eharaeters  nn  the  t;s's  SO- 
coKniin  tifxt  screen  (instead  f>f  the  super  hjgh-resiilution  Jicrt'en  used  hy  QuickDraw 
II).  and  to  send  data  to  a  printer.  Although  these  uses  will  be  emphasized  in  this 
chapter,  the  Test  TonI  -Set  in  general  enough  tu  work  with  any  character  device  in 
any  slot  nr  pert,  or  with  custom  RWl-based  I/O  drivers. 

The  start-up  and  shut-dov.ii  functions  for  the  Text  Tool  Set  are  TextStartup  and 
TextShutDown,  Neither  one  Tequires  parameters  or  returns  results, 

LOCICAL  DEVICES  AND  MASKS 

Tlie  functions  in  the  Text  Tool  Set  deal  with  three  logical  LIO  devices; 

■  An  input  device 

■  An  output  device 

•  An  error-output  device 

The  error-output  device  is  the  device  to  which  an  application  can  send  error  mes- 
sages or  status  reports  without  interfering  with  what  the  primary  output  device 
receives. 
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You  can  assign  rafli  logk-iil  devk-e  to  any  sloi  or  port  on  the  CS  llial  interfaces 
with  a  tliiiTUctcr-ljiised  I/O  device'.  In  a  typical  hardware  cnnfi^iiration.  tlie  cKoices 
for  oiilpii!  clfviL't^s  are  a  printiT  in  port  #1,  ii  iinidt'in  in  port  #2,  and  am  SO-t-tilunin 
video  Screen  in  port  #3  The  input  devit-e  is  uiauully  the  keyboard  (il  is  supported 
throufih  the  video  screen  port  #3)  or  tlie  modem,  in  pari  #2.  The  defaull  devitc 
assignment  ior  all  three  dtvitcs  is  port  #3. 

Device  Uriver  Tvpcs 

Yaii  can  iisiiigii  a  speciRc  type  of  devlL-e  driver  to  each  of  t^e  three  logical  devices 
with  Test  Tool  Set  fiim-tioti.s.  The  three  choices  are; 

•  BASIC  driver  (driver  type  code  0) 

•  Pasesl  11  driver  (driver  lyiie  tode  U 

■  RAM-based  driver  [driver  type  code  2:1 

A  BASIC  driver  is  one  which  adherr.^  to  Apple's  Applesoft  pmtwol  for  initialization, 
input,  and  output.  According  io  this  protocol,  the  ienlr>  (xjints  for  the  driver  must 
be  as  fnltows: 

•  SCnOO  (injtializatioii) 

•  SCn05  {input;  character  returned  in  accumulator) 

•  $Cii07  (output;  character  in  accumulator) 

where  n  is  the  port  (or  slot)  number.  The  GS's  two  serial  ports  and  the  SO-colnmn 
video  port  suppnrt  this  protOLoI. 

A  Pascal  1. 1  driver  uses  j,  tlifferenl  prittocol.  first  developed  Ibr  the  Apple  UCSD 
Pascal  operating  system,  Such  drivers  contain  a  lool«-np  table  at  5>CnOD  to  $Cnl3 
that  TOiitains  the  low-order  b>  les  of  the  addrcs^cs  of  the  subroutines  for  liandiing 
initialization,  inpul,  output,  status,  device  control,  and  device  interrupts,  The  hi^h- 
order  bytes  are  always  SCn.  Any  driver  with  a  value  of  $.J8  at  SCn05  and  a  value  of 
■lilS  at  location  $Cnf^7  supports  the  Pascal  11  protocol.  This  includes  the  serial  ports 
and  video  port  on  the  gk. 

You  can  also  use  your  own  R.AM-based  drivers  if  you  wish.  Sueh  drivers  must 
support  five  fundanirntal  subroutines;  initialization,  inpnt,  output,  status,  and  con- 
trol. Ttit?  addresses  of  ihcse  subruutines  must  appear  in  a  table  at  the  beginning  of 
the  driver-  Each  address  is  a3-byte  absolute  address  (low-order  bytes  first,  as  usual). 

The  GS  calls  IWM-basrd  driver  entry  points  with  ;i  JSL  instruction  while  in  full 
native  mode.  SO  driver  ^ubroiitiiiEts  must  end  with  an  RTL  instruction.  Character 
transfers  between  the  tool  function  and  the  driver  use  the  low-order  8  bits  of  the 
accumulator. 


436    Using  the  Text  Toot  Set 


Bec-ause  the  Ga  internal  character  I/O  ports  support  both  the  bASiC  and  Faaoal 
priJtncols,  you  tun  ±ssi%n  a  driver  type  ttidp  of  0  or  1  to  itit-  Ingical  devices.  The 
defaiih  driv(T  tyjie  ih  BASIC,  althnupli  the-  delimit  is  only  st-t  up  when  ProDOS  16 
first  starts  up.  There  is  no  way  for  an  applkatiun  In  tell  what  the  driver  type  wd! 
be  when  il  «fts  Lontroh  so  the  applitation  ninst  always  explieitly  Rel  the  driver  type 
uiin^  the  leclniiques  dcscrihed  below. 


Data  Masks 

When  handling  I/fl  openitions  invtilving  ASCII- encoded  text,  il  is  important  to  set 
the  hiRh-,irder  hit  (hit  7J  properly.  The  ASCII  standard  dops  not  us.;  this  bit,  so 
many  peripherid  devices  expctt  it  to  b*!  0.  Most  printers,  fnr  csample.  will  want 
the  high  lilt  olT  unless  yoti  arf  tninE  to  print  spraal  svinhok  lhat  itre  assigned  to 
codes  above  The       BASK:  80-L-.ilumi)  text  screen  drivt-F,  on  the  other  hand, 

insists  on  receiving  chsraeters  with  the  hi^b-order  bit  set,  and  keyboard  input 
submuliney  on  Apple  II  computers  traditionally  return  characters  with  the  high- 
onh?r  bit  set. 

Thr  lexl  Tool  Set  always  manipulates  the  bits  in  a  byte  >'iju  send  or  receive  bv 
loRically  ANDinE  the  byle  with  an  .A.\D  iiia.sk  and  then  lugieally  ORinjJ  thr  result 
with  an  OH  inisk  {unless  >ou  are  using  a  RAVJ-btiied  driver),  There  are  AND  arid 
Oil  niaslis  for  each  af  the  three  logical  devices, 

On  initialization,  tb<?  AND  masks  for  the  inpiu,  output,  imd  errnr-output  devices 
are  sel  td  SFF  and  the  OR  masks  are  set  to  SWO-  This  fr^rces  the  high-order  bit  of 
incoming  and  outgoing  data  to  1  and  is  the  rurmat  expected  by  BASIC,  the  default 
driver  type. 

\\  hen  sending  data  lu  a  pniiter,  you  usually  want  to  clear  (he  higli^tirder  bit  of 
outgoing  data  to  0,  To  do  this,  thangc  the  outjxit  AND  m:isk  to  S7F  and  the  OR 
mask  to  $00  with  the  SetOutGlobds  function: 

PLi^hWond  #t7F  ;The  new  AND  mask 

PushWord  #tO0  jThe  ticw  OR  mask 

.SclDiJlGlobala  ;(or  Setin,  SetErr) 

(Use  SetlnGlobals  and  SetErrfilobals  for  the  other  two  logical  devices.) 

When  usins  iin  ImageWriter  II  printer,  the  state  of  the  high-order  bit  is  usually 
unimportant,  because  the  bnagcWriter  II  norinalh  forties  the  hish-order  bit  of 
incOniiuE  data  to  i).  li\  however,  yon  specifically  enable  reenyiiition  nf  this  bit  (with 
a  speci^d  printer  eoinmand:  SIB  ?&6X  $0(1  m).  perhaps  to  allow  printing  of 
MngseText  icons  that  have  codes  from  SC:()  to  ,SDF,  you  dn  not  want  the  high-order 
bit  to  he  altered.  In  this  sitLiation.  you  wiiuld  chanf;e  the  jnasks  to  *Fr  (AND)  and 
sot)  [OR)  and  use  an  AND  #srF  instruction  to  speeiRcally  clear  the  high-order  bit 
oi  a  tc.vt  character  before  printinjj  it. 

To  determine  the  aetive  AND  and  OR  masks,  use  the  GetJnClnbals  {input  device). 
GelOutCdobiJs  (output  device  ),  ttnd  GelErrC;lab3ls  (error  output  device)  f^jnctiotlS: 
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PHfl  ; space    for    AND  masi 

PHfi  ispac?  for   DR  maali 

_GetDutGlobals  -(or  Cetlri,  OetErr) 

PL^l  iPop  thi?  OS  mask    (low  byle) 

PLX  -Pop  the  AMD  mask   (low  byte) 


You  might  use  thest'  fiincliotis  to  save  the  existing  masks  so  that  you  can  restore 
them  whrn  you  exit  yiiur  program. 

CHANCING  active:  DEVICES 

Before  you  pcTfoniliiip  chiiracter  I/O  operations,  you  iiiitst  select  your  three 

active  deviteji,  initialize  ihein,  and  j,p|c-ct  appropriate  AND  and  OR  masks.  To  select 
a  device,  use  the  SctlnputDevit-e,  SetOiitput  Device,  and  Set  Error  Device  functitins. 
Each  requires  two  paramplers:  a  deviLP-typr  rode  word  and  a  long  word  containing 
the  pint  or  slot  number  of  the  device  or  the  address  of  its  RAM  -hfised  driver. 

For  example,  Siere  is  how  to  select  the  printer  attached  to  port  #1  as  the  active 
output  device: 

Pu5hWord  #0  ;0  =  BftSIC  driver  type 

PuahLong  #1  jport  1 

_5etDutpulDeulce 

The  Erst  parameter  pushed  on  the  stack  is  the  driver  type  code  [use  0  for  a  BASIC 
driver);  the  second  is  the  port  number.  If  you  were  using  a  li\M-ba.sed  driver  with 
the  printer,  the  second  parameter  would  be  the  address  of  its  siibroutine  address 
table. 

If  you  need  to  know  what  the  currently  active  device  is,  use  die  Get!  npntDc  vice, 
CctOulpufDfvic<=,  and  GetErrorDevice  functions: 

PHA  ^Space  fo-r  device  type 

f'Hfl  iSpace   for   slot   riirnber  flonq] 

PHA 

_Gfl  tDutpulDevic^  i(or  Getl npu I  ,   Get  Er  ror ) 

PopLcsng  DulputPorl  ;Pop  result 

PQpWnrd  DeviceType  iPop  resulE 

These  funetions  each  return  a  device  type  L-odp  (word)  and  a  slot  number  or  a  pointer 
to  a  RAM-ba.s.ed  driver  (Itmg  wordJ. 

Im'tifllizatrnn 

Once  you  have  assigned  an  active  device  for  input,  output,  or  ermr  output,  be  sure 
to  inieialiiie  it  with  InltTextDev-  ff  you  do  not  do  so,  it  probably  will  not  work 
properhv  To  use  InitTextDev,  pass  it  a  word  describing  which  device  you  wish  to 
initi^li]ee: 
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PiifhWard  TheDevlcE  ^DtvLce  to  initialize 

The  permitted  values  for  TheDevice  arc  0  (input  device],  1  [output  device),  and  2 
(error-output  dfvin;). 

The  efffct  oi'  initializutipn  varies  from  device  to  device.  When  you  initiahzc  the 
port  #3  nutpuE  device  (the  video  scn-enl  for  uutput,  for  exiiniple,  the  screen  clears. 

The  suhruuUnes  shown  in  lislinj;  12-1  illustratp  hnw  you  might  eDtiblf  video  port 
#3  for  output,  a  printer  in  port  #1  for  output,  and  the  keyboard  for  input 

SENDING  CHARACTERS  TO  THE  OUTPUT  DEVICE 

There  are  five  different  ways  you  can  send  a  character,  or  a  group  of  characters,  to 
the  standard  output  device.  The  method  you  will  use  depends  on  how  the  textual 
information  is  arranged  in  m«mOry. 

The  Bve  techniques  are  summiirized  below: 


WriteChar  Seud  a  sinnle  chimifter 

WriteLine  Send  a  sequence  of  charaeters  thai  is  preeeded  by  a  length  byte; 

then  send  a  Carriage  Hetum  tode 
WriteStriug  Send  a  sequence  of  characters  that  is  preceded  hy  a  length  byte 

TextWriteBiiK-'k       Send  a  fipeciiied  sequence  of  characters 

WriteCStrin;^         Send  a  sequence  of  characters  that  is  tenninatcd  by  a  $00  byte 

(Similar  lUnctions  exist  fnr  the  error-output  device:  ErrWriteChar,  ErrWriteLine, 
ErrWnteStrinS,  ErrWriteBlock.  and  ErrWriteCStrins.) 

All  these  methods  pr£K.-ess  oiitjioing  eliaractcrs  by  first  ANDinp  ttiem  ^.vitk  tlie 
AND  mask  and  then  ORing  them  with  the  OR  ma^k. 

Single  characters  are  best  handled  by  WritcChar: 

PuBhWord  #»i)OSD     iPush  with  character   in  low  byte 
„Ur  i  teChar 

To  send  a  group  nf  characters,  you  could  make  multiple  calls  to  Writf-Cliar,  but  this 
is  slow  and  ineEitient-  If  the  text  is  in  Pascal  string  format  (thai  is,  if  it  is  preceded 
by  a  length  b>'te),  use  WritcStriiis  instead; 

PuatiPtr     MyString  ;Pointer    to  atring 

Wr  1  teS 1 r  ing 
RTS 

MyStrIng     STR   ''Thla   Is  s   siring'  ;Text   of  string 

Use  WriteLine  in  the  same  way  if  you  want  a  carriage  return  code  sent  after  t5ic 
string  is  sent. 
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ir  I  he  text  is,  in  C'Strinij  fiirmal:  (that  is.  if  if  is  Folliiwt^d  hy  a  zern  h)  t('.  with  no 
Icnglli  hylt  L  use  WrileCStriiie  instead  ol  WriteStrin^.  There  is  nn  C  equivalent  to 
WritcLine.  however. 

Displayinc  lex[  striiij^s  is  sufli  a  eiiniTnun  event  that  it  is  eonvt'iiitrnt  to  use  macro.'! 
to  handle  it  Tlie  PRINT  maeni  in  Msling  12-2  sends  a  siriiip;  ^ipeeified  in  its  arj^uuifiil 
to  ihr  output  device.  In  a  prograin,  invoke  PRINT  by  placin^r  the  string  in  singlt? 
[[uott  m^kis  after  the  macro  name; 

PRINT   'Print  this' 

If  the  string  include^  a  single  quote  mark  as  part  of  the  string,  specify'  two  single 
quoti^  mark.'i  in  a  riiw, 

The  PKlNTLN  inacro,  alsij  iihown  in  hstini^  12-2,  is  similar  tn  PRINT  hut  it  uses 
WriteLJiie  instead  nd  WnteStrin^,  As^  a  i-esult,  it  stntl^i  a  earrjayc  return  code  alter 
the  specified  te\t  string. 

Tn  send  any  iequente  uf  eharbleters  inside  a  largt  hlucfe  uf  tqxl,  use  Tcxt- 
WritcBlock: 

PiiShPlr    TheText  ;PDinter    to    alort    of    text  block 

PushWord  Offset  ;Character    to  begin  with 

Push  Wo  rd  Count  jNumber   of   characters    to  ae-nd 

_TejctWriteBlocli 

Text  Write  Block  sends  the  "Count '  charaLters  beginning  at  a  position  "OiFset '  bytes 
from  the  start  of  the  text  block  pointed  to  by  TheText. 

READING  CHAJftACT£HS  FROM  THE  INPUT  DEVICE 

There  are  three  basic  character  re»din^  tunetion^i  in  the  Text  tool  set:  R!?adtrhar, 
ReadLinf,  and  TextB  cad  Block.  The  one  you  will  use  most  often  is  RcadChar, 
because  it  grabs  niH->  character  at  a  time  from  the  keyboard  [dsitumins^  port  #3  is 
the  inpiit  port],  which  is  how  most  proj^rams  prefer  tlc-abng  with  keylxiard  input. 
Here  iii  how  to  use  it: 

PHfl  japaceforreiult 

PushWord  Echaflaq  ;1    -  echo.    D   -   don't  echa 
_Ppac[Char 

PLfi  ;Pop  ctiaracter   (low  byte) 

The  EchoFlag  indicates;  whether  you  want  to  et.ho  incoming  data  to  the  (mtput 
deviee.  In  most  situations,  ytiu  will  set  it  to  1  lo  enable  ecboinp. 

ReadLine  keeps  readint;  characters  nntil  it  receives  an  eiid-of-line  (EOL)  eliar- 
acter.  which  in  usually  a  carriaur  return  code  (SftD),  or  until  a  speciHed  iiujnber  of 
characters  have  been  received.  On  exit,  it  returns  the  nnmher  of  characters  received. 
Here  is  how  to  call  ReiidLine: 
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PHfi  ispacp  for  result 

PushPtr      IrputBuffer  ipointer   to   input  buifer 

Pu!fiWord  MsxCoufit  jsiic  ai  bu-ffer 

PushUprd  idJSD  jEOL  character 

Pu^hWord  EchO'Flag  jl    =   echo,   0   =  don't  echo 
_ReadL i ne 

PLft  ;Pop  character  ciiunt 

InputBuffer  is  (he-  art-a  liC  iiiemi)r\-  in  wllich  the  incoming  characters  are  stored 
MiLvCouiit  is  the  maximuiii  linv  U-ngth,  which  Tiiiist  be  less  th^  the  biiffFr  size. 

The  last  char^L-ter-rL-adiiig  fiinc-tiuii  is  TextRcadBlitck.  With  it,  yu;i  can  rfad  in,  a 
j;rtmp  ui' charactt-rii  aud  place  them  at  a  specilii-d  Itxralion  inside  a  text  buffer: 

Pu5hPtr  Textflrea  ;Pajiiter   lo  start   of   Isxt  area 

PushWord  Offset  ;Cffaet   to  start  of    input  block 

PushUar  d  Count  ; Number   of   character?    to  read 

PushUard  EchoFlog  ;1    =  echo,   0   =  don't  echo 

_Te3(tfieadBlocl< 

The  problem  with  using  TcxtReatJBlock  is  that  il  does  nnt  exit  until  it  reeeives 
Count  charat'ters.  ReadLinc?,  an  the  other  hand,  always  pxits  when  it  receives  the 
EOL  characfer. 


KEYBOARD  INPUT 

One  funotion  the  Te\t  TonI  Set  cannot  perforin  is  tn  cheek  wliethrr  or  not  a  key  has 
been  entered  frtim  tht  keylward-  Vnu  will  want  to  do  fliis.  for  esan^ple,  il  you  design 
a  proj^rain  loo[}  whieh  is  to  eontinue  locipitiR  until  the  user  presses  a  key.  You  cannul 
CSC  KeadChar  because  il  waits  until  a  key  has  been  pressed  Ix'Inre  returning  eontrtil 
to  the  applic3(ion.  One  solution  is  to  access  the  keylKjard  I/O  Ineatiuus  directly,  ill 
the  E\ent  Manager  is  active,  you  can  keep  k>oping  until  tietNextEvent  or  Task- 
Master  indicates  that  a  key-down  event  occurred  ! 
The  two  main  ke> board  I/O  locations  are  as  loUows; 

*  SEOCCXIO       keyboard  strobe  (bit  7)  +  data 

*  SEflCOlO       elear  kevlward  strobe 

When  you  are  accessing  these  locations  {or  any  other  I/O  locatinns  for  that  matter), 
the  m  status  ilag  must  be  set  to  1  so  that  read  or  write  operaticmy  afifect  the  one- 
hyte  I/O  location  only.  Tins  is  ver>"  important, 

Tu  detcnninc  whether  or  not  a  "key  has  been  pressed,  check  the  higli-order  hit 
iif  SEOaXHl  (the  keyboard  strcibe^  bit).  If  it  is  1,  a  key  hiw  been  prt-ssed  and  the 
lower  se^  en  hits  of  ^EOClKXf  contain  the  key  s  ASCII  character  code.  To  clear  the 
keyboard  5tTi>he  si>  lliat  the  nt  st  read  of  $E(XJOL10  «ill  not  return  the  same  kcycode. 
access  the  SEDCOlO  I/O  lotatiiui. 


Keyboard  Input  441 


Here  is  a  short  subroutint.-  yttti  fuuld  call  to  chet?k  the  Status  of  the  keyboard: 

CtieckKbd     SEP       #120  ^8-bit  accumulator 

LOHCfl  OFF 


LDfi  lEaCOOD  ;Check  keyboard 

BPL  KbdExil  ; Branch    I*    nolhing  there 

SJft  SEOCDU  ;  Clear  strobe 

irbdExit        REP  #(20  -.lE-bit   accLimj  1  a  t  or 

LDNGft  ON 
HTS 


II  a  key  lias  beeii  pressed,  the  negative  flag  is  set  tu  1  and  the-  ch<iraL'ter  cflde  is 
reliinied  in  tlie  accumulator.  If  no  Itey  has  been  pressed,  the  neaative  fla^  is  deared 

tn  n. 

Yuu  must  t-arpfiil  while  aceessing  keybuard  I/O  lunations  wliem  keyboard 
interrupts  arc  enahJed,  heeaust'  all  keypresses  will  he  processed  by  an  interrupt 
handifr  hrfnrf  yiiii  ha^r^  a  cfianif  t(!  read  $EOC0<X)  t(i  deleniiine  whether  or  nut  a 
key  has  ht^en  pressed.  (Remend>er^  keyboard  interrupts  are  iiuioinntically  enabled 
if  the  Event  Manager  is  in  use.)  This  is  a  particularty  important  consideration  when 
devekipin(^  dt^sk  accessories  because  they  may  be  activated  at  any  time  fmm  any 
appliuatiun. 

Yoo  can  check  whether  keyboard  interrupts  are  enabled  by  caHinji  the  Get- 
IRQEoabie  fiinction,  in  the  Miscellaneous  tool  set: 

PHA  ;5pace    for  result 

.Cetll^QEnBble 

PLA  ;&et   5tdtu5  word 

ir  keyboard  interrupts  are  enabled,  hi!  7  of  the  status  word  result  will  be  set  to  1. 

Wlieii  interrupts,  are  enabled,  you  must  first  disable  keyboard  interrupts  with 
InlSource,  another  runctiaii  in  the  Miscellaneous  tool  set,  Here  is  how  to  disnhle 

PushWord  #1  t'    -  disable   keyboard  interrupts 

I nlSource 

Later  in  the  program  you  can  re-enahle  keyboard  interrupts  by  passing  a  SOO 
parameter  to  IntSource,  but  only  do  this  if  interrupts  were  enabled  in  the  first 
plaL-e. 
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ApplicaHoiis  using  the  8[l-colLiinti  text  screen  cannut  take  advantnge  of  tool  sets  like 
the  Window  Mjnaper,  Menu  M;iiiag,tT,  and  Dialog  Manager  bteaitse  these  tng|  sets 
wnrk  with  the  super  high-resolutiun  scrreii  only,  Thus,  you  have  to  do  a  lot  innre 
work  if  viiu  wish  to  fallow  desktnp  interface-  jiuidelines.  Nevertheless,  tPNt-hased 
applications  are  popular  altcniiitives  to  similar  iirapliics-hasod  ones,  hecaase  screen 
operations  such  as  scrolling  and  iipd^tin^  take  phce  more  quickly, 

The  drivers  for  most  intt  llii^fnt  output  deviees  support  sets  of  commands  you 
tan  use  to  control  the  way  tlu:  devicei  handle  subsequent  charaLtL-rs.  In  niost  cases, 
a  command  if*  cither  a  etjntrol  cSiaiacler  (a  character  with  an  ASCII  Lod«?  Irun\  t)  to 
31)  or  a  control  character  folluWfd  by  A  series  of  characters  in  a  certain  order. 

The  driver  for  the-  fiO-ctjIinmL  loIuuiii  test  scrripn  hi'i  Lommands  iUdl  (with  one 
cxccptitjnj  arc  single  cnntrul  cliaraeters.  You  can  use  these  c[>]nini3,nds  lo  perlbrm 
such  cst'fiil  actions  as  screen  clearing;  moving  the  cursor  position  up,  down.  left,  or 
riyht:  ciT  hiKhlijjhtinu  subsequent  characters.  The  cununands  supported  hy  the 
BASIC  and  Pascal  drivers  for  the  Bn-column  text  sereen  are  suininarizcd  in  tahle 
12-1. 

Notice  that  the  ASCII  codes  givf-n  in  tahle  12-1  have  the  high  bit  set  because 
the  SU-eolumn  video  driver  expects  characters  in  tliis  Ibrniat.  If  the  output  OR  maslt 
is  S80  (the  usual  case),  you  can  also  scud  codes  witli  the  high  hit  off. 

Also  notice  (hat  for  the  Pa.sciil  driver,  the  CH  (carriage  retnni)  code  does  not 
move  the  cursor  to  tlae  iicxi  line  as  it  doeii  wheii  the  BASIC  driver  is  bein^  used. 
You  must  follow  the  CB  with  LF  (3ine  feed]  to  move  the  cursor  down  one  line. 

Character  Display 

Tahle  12-2  shc)ws  which  charticters  appear  oh  the  text  ^cTcen  when  you  send  ASCII 
eodes  from  $A0  to  SFK  to  the  8I>-coIinnn  ■video  driver.  These  characters  are  usually 
displayed  in  nnrmal  video  {white  characters  on  a  black  backpround)  but  this  mnde 
can  be  inverted  by  seudini?  a  $8F  (INVERSE)  ctxle  tc>  the  driver  first.  To  return  tij 
normal  video,  send  a  SSE  [NORMAL]  code. 

Mouse  Text 

MouseText  is  a  group  of  thirty-tv,-o  icons  representing  such  objects  as  apples,  arrows, 
checkmarks,  a  flic  fohier,  scroll  bar  arrows,  and  shading  ijatterns  Y<iu  eau  use  them 
to  add  a  little  spice  to  your  screen  displays. 

Each  MouscText  icon  c^irrespunds  to  a  Standard  keyboard  character,  as  shnwii  in 
table  15^2.  To  display  a  MmiseTe.Kt  character,  fir^t  enable  the  driver's  handling  of 
MouseText  hy  seudinj;  a  S9B  code  [MTXT_ON)  and  turn  on  inverse  video  by  sending 
a  SSF  cude  (INVERSE).  Then  send  the  code  for  the  character  corresponding  to  the 
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Table  12-1:     Control  Commands  Sniiported  by  the  SO-Colvuun  Screen  Driver 


ASCII 
Code 


Symbolic 
Name 


Action 


$85 
$86 
$87 

safe 

S8C 
$8D 


SSF 
$91 
$92 

$95 
$% 

$97 

S98 


S9A 


CL'HSOROFF 

CURSORON 

BEEF 

BACKSPACE 
LF 

CLREOP 

CLRSCREEN 

CP 


NORMAL 

INVERSE 

SET_4{)COL 

SET_80f:OL 

PAUSF. 

FlftM.OFF 

SCROLLD 

SCROLLU 

MT\T_OFF 

HOME 

CLRLINE 

MTXT.ON 


Do  not  display  a  cursor 
Display  a  cursor 

Sound  a  tone;  voliimt!,  pikh  set  by  Cnntrol  Panel 

Move  the  cursor  left  uiie  position 

Line  feetl;  move  the  cursor  down  one  line 

Clear  the  stTeen  froin  the  current  cur&ur  position  to 
the  t'ntl  of  the  screen 

Clear  the  screen;  move  the  tursor  la  the  top  left- 
hand  comer 

t;arriafic  return;  for  BASIC,  move  the  cursor  to  the 
left  -side  of  the  next  line;  for  Pascal,  move  the 
tiirsor  lo  the  left  side  of  the  current  line  (follow  CU 
with  LF  to  move  the  cursor  dovm  one  line) 

Enable  the  normal  mode  fnr  text  display 

Enable  the  inverse  mode  for  ttxt  display 

Enable  the  ■lO-column  scrc^fn  display 

Enable  the  SO-eolumn  screen  display 

Stop  receivinc  characters  until  a  Itey  is  pressed 

Turn  nfl  the  SO-cnlumn  display  and  Rrmware 

Scroll  the  display  down  one  line;  leave  the  cursor  at 
the  same  position 

Scroll  the  display  up  one  line;  leave  the  cursor  at 
the  same  position 

Show  inverse  upper-case  characters  instead  (A 
MuuscTexl  characters 

Move  the  cursor  to  the  home  position  (the 
top  left-haiid  corner  of  the  screen) 

Clear  the  (^ntire  line  on  which  the  cursor  is 
positioned 

Show  MnuseTcxt  charaLters  instead  of  inverse 
upper-case  characters 


444     Using  the  Text  Tool  Set 


Table  IS-l:  Conliniied 


ASCH  Sijinholic 
Code  •Vum^ 


Action 


$9C  moverj(;ht 


$9D  CLBEOL 


$9E  SET.CL'ftS 


»9E  GOTOXY 


«9F  MOVEUP 


Movp  thf  L'ursor  one  positinn  ta  the  right,  nitiving 
lo  the  next  line  if  nctessan' 

Clear  the  screen  from  the  furrejit  curfinr  iwsilion  to 
the"  end  of  ihe  lint" 

For  the  BASiC  driver  only:  Change  the  cursor 
chiirafter  to  the  character  which  follows 

Far      Pascal  drivt-r  onhj:  Move  the  uursor  to  the 
position  iiidifatL'd  by  the  Iwo  hytfs  that  follow;  the 
First  byte  i.s  the  hurizonlBl  position  plus  32;  the 
second  is  ihr  vertical  position  phis  32 

Mo%'e  the  cur-iur  up  one  linr  liii  the  same  tohinin); 
do  not  mmp  if  the  cursor  is  in  the  lop  line 


MoiiseTesl  icQO.  Codp  SCl  (A>,  for  example,  represents  the  Open-Apple  icnn.  If 
yoii  want  the  driver  to  display  inverse  chiiracters  instead  of  icons,  send  code  $9S 
(MTXl_OFF)  lo  disahlc  the  conversion  to  MouseText  icons. 

These  are  itie  MoiisiTcxt  ^.ymhols  and  thL-ir  corresponding  ehanicters  (they  tor- 
respond  to  the  codes  from  SCO  to  SDF): 


MouseText- 
normal  - — 


l<fci6|K|X 


=IH-l^^l1-rMIBI^ 


^^ABCDEFGHI JKLMNO 


MouseText- 
normal  


■*PQRSTUVVXYZI\]  *_ 


Cursors 

A  cursor  marks  the  position  on  ihi.^  screen  at  which  the  next  displayable  chaiucter 
you  send  to  the  videtj  driver  will  appe;n-.  II  is  normally  a  solid  white  htw,  formed 
by  displaying;  an  inverse  spi^ce  charatter. 

If  you  art-  using  the  BASIC  video  driver,  you  can  change  the  cursor  to  any  other 
character  by  sending  a  -^^E  (SET.CURSl  comnLaiid  In  the  video  driver,  followed  by 
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Tahk'  12-2:      Synibtjis  for  the  Disptayable  ASCII  Character  CaJes 


ASCII 
Code 

Symbol 

ASCII 
Code 

SAO 

scu 

^■ 

SEO 

+ 

SAi 

r 

A 

SEl 

a 

$C2 

B 

SiE2 

b 

$A3 

# 

$C3 

C 

SiE3 

e 

$A4 

S 

$C4 

D 

£E4 

d 

$A5 

% 

$C.'> 

E 

$E5 

e 

$A6 

$c:fi 

F 

SE6 

f 

IS  A  7 

■ 

*C7 

G 

SET 

g 

SAS 

( 

scs 

H 

$E8 

h 

.SA9 

! 

r 

SE9 

i 

SAA 

+ 

$CA 

J 

$EA 

j 

SAB 

+ 

SCB 

K 

SEB 

k 

$AC 

> 

sec 

L 

SEC 

1 

SAD 

— 

SCD 

M 

$ED 

m 

SAE 

■ 

$CE 

N 

SEE 

n 

SAF 

/ 

SOK 

O 

SEF 

0 

SBU 

0 

*D0 

P 

$F0 

P 

$B1 

1 

$D1 

Q 

*FI 

q 

SB2 

2 

$D2 

R 

$F2 

T 

SB3 

3 

-SL?3 

S 

SF3 

S 

SB4 

4 

SD4 

T 

SF4 

t 

SB5 

5 

SD5 

U 

SF5 

u 

*B6 

6 

SDH 

V 

$F6 

V 

$B7 

7 

SD7 

W 

$F7 

w 

$Bd 

S 

SD8 

X 

$F8 

% 
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Table  12-2:  Continiifd 


ASCII 
Code 

Siftnhol 

ASCII 
Code 

Symbol 

ASCII 
Code 

Symbol 

$B9 

9 

SD9 

Y 

$F9 

y 

SBA 

$DA 

% 

$FA 

z 

$BB 

«DB 

[ 

$FB 

{ 

SBC 

< 

SDC 

\ 

SFC 

SBD 

$DD 

I 

$FD 

} 

SBE 

> 

$DE 

SFE 

$BF 

? 

SDF 

*FF 

[mbout] 

thf  (-odf  for  iirw  chartiftier.  Thert  are  al^ti  cummilntis  for  turning  the  cuc'sor  on 
and  <iff:  use  SS6  (CIURSORON)  to  turn  it  un,  anil  S85  (CURSOKOKF)  la  turn  it  o(F 

If  you  are  using  the'  Pascid  driver,  yoa  uiUi  podtiun  the  tursor  by  sending  a  $9E 
fiide  fCOTOXY)  followed  by  bytes  repriesffntinp  tfie  liorizonlal  and  vertical  positions. 
These  positions  are  (ifiKet  from  th<'ir  actual  positiun!)  by  32  so  that  position  (2,4)  is 
represented  by  (34,36),  ftir  example 

The  BASIC  SL-reen  driver  dues  not  support  a  curjor-positiomng  command*  To 
sert'(?  thii  purjjose,  you  will  ha\  e  to  Ldll  u  subroutine  hke  the  one  in  listing  12-3. 
On  entry  to  the  Subroutine,  the  horizontal  position  must  be  in  X  and  the  vertical 
pusition  in  Y, 

To  understand  how  this  subroutine  works,  consider  that  the  C5  BASIC  SO-column 
video  driver  keeps  track  of  the  current  cursor  position  in  three  locations  in  page 
zeio  and  pape  five  of  bank  $00: 

"  CH  ($24)       horizontal  cursor  position  (0  to  79) 

■  OURCH  ($57B)        duplicate  of  horizontal  t-ursor  ptisition 

•  CV  ($25)       vertical  cursor  position  (0  to  23] 

To  change  the  cursor  position,  you  must  place  the  new  horizfltital  pttsition  in  both 
CH  and  OURCH  and  the  new  vertical  position  in  CV.  ^The  position  is  autoniiitically 
updated  as  you  send  charatters  to  the  screen.  ]  Tlierr  is  a  compHeation  that  arises 
when  CV  is  chaTiged,  however.  The  BASIC  driver  continues  to  uae  the  old  CV  value 
untd  the  cursor  actualK  moves  to  another  line.  To  force  Pfi  immediate  repositioning. 
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Table  12=3:    Tlie  flO^CoEumn  Test  Screen  Panmiettrs  for  Windowing  and  C 
Ctlntrnl 


Bank  $00 

Sifmbolic 

Address 

Name 

Descripiion 

$20 

WNDLFT 

Left  ttiiumn  of  window  (0  to  79) 

S21 

WNDWDTH 

Width  of  window  (1  to  80) 

S22 

WNDTOF 

Top  row  of  window  (0  to  23) 

S23 

WNDBTM 

Bottom  row  of  window  plus  one  (1  to  24) 

$24 

CH 

Horizontal  cumiT  position  (0  to  79) 

S25 

CV 

Vertical  cursor  position  (0  to  23} 

«57B 

OURCH 

Horizontal  cursor  position  (0  to  79) 

NOTE  WNDWDTH  must  nol  exceed  80  mlniis  tlie  valiit-  orWNDLST 


you  must  plat-e  thq  desired  value  minus  1  in  CV  and  then  send  a  carriage  return 
code  to  the  output  device.  This  is  exactly  what  the  GOTOXY  subroutine  dtK-s. 

The  COTOXY  ^iuhroutine  alsu  showis  how  to  force  Iohr  addressing  {by  putting  a 
>  in  front  of  the  lahtd  for  an  address)  so  that  you  do  not  have  to  change  the  direct 
page  before  writiup  to  CH  orCV,  It  also  temporarily  switches  to  an  S-hit  acx-umulator 
50  that  when  you  store  the  accumulator,  the  next  legation  in  memory  i&  not  over- 
written. 


Window  Dimensions 

The  yO-coliimn  BASIC  video  driver  is  normally  able  to  display  characters  anywhere 
on  the  screen.  Yon  can,  however,  tell  it  to  confitie  its  operations  to  any  rectangular 
window  within  the  screen  by  redefining  four  window  houndart"  parameters  located 
in  page  zero  of  hank  $00,  These  parameters  arc  described  in.  table  12-3. 
The  usud  values  fur  the  parameters  in  table  12-3  are: 

WN  DLFT  0  (left  edge  is  column  (J) 

WNDWDTH  SO  (screen  width  is  80  columns) 

WNDTOP  0  [top  line  is  line  0) 

WNDBTM  24  (bottom  line  +  1  is  line  24) 
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As  when  changing  CH  or  CV,  you  must  switch  to  an  S-bit  accumulator  before  storing 
a  number  tn  any  of  the  v^-indow  parameter  locations. 

One  paramt-ter  voli  must  handle  tarefiilly  is  WNDWDTH  U  must  not  exceed 
the  difierencc  between  80  {the  maxiimim  window  width!  and  WNDLFT  {the  left 
edge).  Keep  thii  in  uiind  whenever  you  change  WNDLFT. 

Note  that  the  window  dimcnsiomug  techniques  do  not  work  when  the  Pascal 
video  driver  is  being  used.  They  uuly  woric  for  the  BASIC  driver. 

PRINTEK  OUTPUT 

Printt-r  drivers  idso  support  a  variety  of  (.onimand?;,  mostly  for  setting  formatting 
parameters  llsat  alibtt  the  appearance  uf  piiriter  output  but  also  for  setting  up  the 
communications  link  wild  the  printer.  The  major  comTuauds  support-rd  hy  the  drivers 
for  the  built-in  serial  ports  on  the  l.s  are  summarized  in  table  12^.  (Driver  com- 
Tuands  more  approjiriate  to  modem  interaction  are  not  given  in  this  table.)  To  use 
a  command,  you  begin  by  sending  a  Control-!  code  (ASCII  Sm)  to  the  driver.  You 
tdn  change  this  attention  code  to  another  contrnl  characrter  with  a  Control-I  Control- 
X  sequence,  where  "Control  s"  represents  the  new  attention  code. 

Default  settings  fijr  most  of  the  printer  piirameters  can  be  set  widi  the  Printer 
Port  eonunand  in  the  Coutrol  Panel  desk  ac^iessory. 

The  drivers  for  the  es  s  internal  serial  ports  [which  can  also  he  used  with  modems 
and  other  serial  devices)  are  not  as  flexible  as  some  iaund  in  many  non-Apple  printer 
interfaces.  Such  interfaces  often  support  several  commands  that  let  you  print  the 
contents  of  the  text  or  graphics  screens  in  many  different  formats  and  si^cs  with  a 
few  simple  commands.  Without  these  commands,  an  application  programmer  must 
write  his  oviti  routines. 

Keep  in  mind  tliat  the  printer  itself  may  support  commands  that  the  printer 
interface  does  not.  For  example,  to  enable  special  printing  mtrtles.  such  as  boldfacing 
or  underlining,  normally  you  send  commands  directly  to  the  printer  [through  the 
printer  driver,  of  course),  if  the  command  fonllicts  with  a  driver  commawd.  you 
may  have  to  first  send  a  command  to  the  driver  that  tells  it  to  ignore  control 
character  interpretation;  for  the  Ci  serial  port,  this  is  the  Z  command.  II  you  do 
this,  you  can  restore  control,  character  interpretation  by  calhng  the  LnilTextDev 
function. 

THE  TEXT  TOOL  SET  IN  ACTION 

The  program  in  bsting  shows  how  to  implement  many  of  the  techniques 

descrihi'd  in  this  chapter.  In  ])articular.  it  shows  how  to  use  the  PRINT  and 
PRINTLN  macros,  how  to  enable  and  display  MouseText  characters,  how  to  position 
the  screen  cursor,  and  how  to  turn  on  the  printer. 
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Table  12-4:     Coiilrol  Comniiinds  Snppnrtpd  by  the  Drivfr  fur  iht  cs  Serial 
Ports,  For  j  Priiitor  Piirt,  <.:ommarids  Muit  Be  Preceded  hy 
Character  SHB  <Control-I), 


Command 


nB 


Action 


Set  the  serial  baud  rale. 


n  =  0  tlefaiilt 
n  =  J  50  b^iid 
n=2  75  hiiud 
n  =  3  110  baud 
n=4  135  baud 
n=5  150  baud 
n=6  3UfJ  baud 
n  =  7  fiOO  baud 


n=-S 
n=9 

ii  =  iJ 
11-12 
11=13 

T1  =  14 

n=15 


i20fl  baud 
imt  baud 
240(1  baud 
.■3R(H1  baud 
4S00  l)aud 
72(K)  liaud 
9600  baud 
19200  baud 


Set  the  number  of  data  hits  and  stop  bits. 
n  =  0  8  data  +  1  stop    n=4  H  data  +  2  stop 
n  =  l  7  dat3  +  1  stop    n  =  5  7  data  +  2  stop 
n  =  2  6  data  +  1  stop    n  =  6  6  data  +  2  stup 
n-.3  5  data  +  ]  stop    n  =  7  5  data  +  2  stup 


TlP 


Set  the  parity. 
n=(l  nu  parity  bit 
n=  1  odd  parity 


n  =  2  nn  parity  Ijit 
II— even  parity 


nN 


Set  the  line  length  to  n. 


CE 
CD 


Enable  [CE]  or  disable  (CD)  line  Ibiinattinf!,  When  enabled,  the 
inserts  a  tarriaKf  return  at  the  end  of  a  line  (the  length  is  set 
by  the  nN  eommand). 


AE 
AD 


Enable  (AEl  ur  dLsablf  (AD)  proper  operatiun  of  the  Applesoft 
BASIC  TAB  commands.  When  enabifd,  the  line  length  is  forced 
t(f  the  video  screen  w  idth. 
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Table  12-4;  CdntiTiuL-d 


String  Action  

BE  Enable  (BE)  or  disable  i&D)  t'trc  biififrinE  of  int-oiiiiiig  and 

BD  outgoing  chuiaL-ttrs.  Tlw  buffers  arc  each  2l)4&  bytes  in  si^e, 

ChariiCtrrs  are  sent  from  the  output  buffer  in  response  tn  an 
inkTi  upt  indiLating  that  the  peripheral  device  is  rt'ady  tu  rtK-eive 
;i  char^'tcT. 


XD 


Enable  (XE)  or  disable  (XD)  the  XON/XOFF  software  handshake 
prfitcNi'ul.  When  enabled,  and  the  firmware  receiver  an  XOFF 
tharat'ter  (ASCtl  S93).  characters  ire  not  transmitted  until  an 
XON  tharaettir  tASC^tl  S91)  is  reteived.  Some  printers  use  this 
tcchnitlue  for  flow  contnjl. 


LE 
LD 


Enable  (LEI  or  disable  [LD)  the  sending  of  a  line  feed  character 
(ASCII  &H\}  after  a  cairiaKC  return  character  [ASCII  $8D). 
EoLible  this  fratoi  e  if  your  jjrinter  seems  tn  print  everything  nn 
otie  lirnj;  disable  it  if  the  printer  double-spaces  all  output. 


R 


Reset  the  serial  ptirt.  This  restores  the  tk-fault  parameter  settings 
set  in  the  Control  i^'an'el. 


2 


Zap  control  character  interpretation.  After  this  coininand,  the 
Urinware  ignores  character  st-<juences  which  would  normally  be 
ijiteq^reted  as  cflinniands. 
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Table  R13-1:     The  Major  FuncftOBS  in  the  Te\l  Tool  SetJWO 


Funclion  Same 


ErrW rite  Block 


Function  Stack 
Numher  Parameters 


TextPtr  (L) 
OfTsct  (W) 
Cnuot  (W) 


DesvriptiQn  of 
Paranwter 


Ptr  to  bloelt  of  text 
Offset  to  Rrst  character 
Number  of  characters 
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FuncHan  Name 

Fiinctioji 

Stack 

DescriptUm  of 

Paran\e(ers 

ParametLT 

Ei-rWritcChar 

$19 

Char  (W) 

ASCII  cliiirdcter  to 
write 

E  rtW  ri  tpCS  triniJ 

Ptr  to  C-stylc  text 
string 

ErrWritffLinc 

$1B 

StringPtr  (L) 

Ptr  to  text  string 

ErrWriieStritiR 

$1D 

StringPtr  (L) 

Ptr  to  tejtt  string 

GetEiTorDevice 

514 

result  (W) 
result  (L) 

Driver  type  t-tidc 
Output  slot  (or  vector) 

GetErrClobals 

SOE 

result  (W) 
result  (W) 

Current  error  AND 
mask 

Current  etrot  OR 

GetlnClobais 

SOC 

result  (W) 

Cunent  input  AND 
mask 

Current  input  OR 
mask 

Getlnpul  Device 

$12 

result  (W) 
result  (L) 

Device  type  code 
Output  slot  (ar  vector) 

GetOutClohflU 

resiiJt  (W; 
result  (W) 

Current  output  AND 
mask 

Current  output  OR 
musk 

G  e  I  Oti  tpu  t  D  e  V  i 

$13 

result  (W) 
result  (L] 

Driver  type  code 
Output  slot  (or  vector) 

InitTextDev 

S15 

DeviceNum  (W) 

Dcvite  number 

ReadChar 

S22 

result  (W) 
liL-hoFlag  [WJ 

Inputted  charaeter 

code 

1  =  ■echo/tl  =  don't 

echn 
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Function  Name 

Function 
dumber 

Stack 

Parajneters 

Description  of 
Paranieter 

ReadLinf 

result  (W) 
BufferPtr  (L) 
MaxCount  (W) 
EOLChar  (W) 
EchuFlag  IW) 

Character  count 

Ptr  to  input  buffer 

Size  of  buffer 

End-i)f-!ine  character 

1  -  echo/0  ^  don't 
echo 

SetErrorDevit-e 

su 

D«'ViceT\'pe  {W) 
SlotOrAddr(L) 

Driver  type  code 

Error  output  slot  (or 
address) 

SOB 

ANDMask  (W) 
ORMask  (W) 

Error  output  AND 
mask 

Error  output  OR  mask 

'£.iatTnr~'1nKalc 
dtHiSLVj  IDDnIa 

AN  DM  ask  |W) 
OR  Mask  (W) 

Input  AND  mask 
Input  OR  mask 

Setlnput  Device 

$0F 

DeviceType  (W) 
SlotOrAddr  (LI 

Device  type  code 
Input  skit  (or  address) 

SetOutGlobals 

SOA 

AN  DM  ask  (W) 
ORMask  (W) 

Output  AND  mask 
Output  OR  mask 

SetOutputDevice 

DeviceType  (W) 
SlotOrAddr  (L) 

Device  type  code 

Output  slot  (or 

address) 

TcxtRead  Block 

S23 

BlockPtr  (L) 
Offset  [W) 
Count  (W) 
EchoFlag  (W) 

Ptr  to  start  of  text 
block 

Offset  to  starting 
position 

Number  of  characters 
to  read 

1  =  echo/0  =  don't 
echo 
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Funt^iuji  Name 


Function 
umber 


Stack 

Parameters 


TestShutDown  ,$03 
TexCStartup  $02 
Tex  tWriteB  lock  $1E 


WriteChdr  $18 

WriteCString  §20 

WritpLiiie  %\A 

WriceString  filC 


[no  paraineters] 
[no  parameters] 
TextPtr  (L) 
Ofifset  {W} 
Count  (W) 
Char  fW) 

CStrmgPtr  (L) 

StrtngPtr  (L) 
StrUigFtr  [LJ 


Descr\]}Uon  of 
Parameter 


Ptr  lo  block  of  text 

Offset  to  first  character 

Number  of  character;; 

ASCII  character  to 
write 

Ptr  to  C-style  text 
litring 

Ptr  to  text  string 
Ptr  to  text  string 


Table  Ria^2:     The  Text  Tool  Set  Error  Cnd*s 


Error 

Code   Dy^cripitan  »/  £rrpr  Ctmdition 

SiOCOl  Illegal  device  type  code. 

S0C02  Illegal  device  number, 

SCtC03  Illejjal  operation. 

Undefined  hardware  error. 

SOCOfi  The  device  is  no  longer  on- 

line. 


Table  RI2-3i     Useful  Functions  in  the  Miscellanenns  Toul  Set  ($03} 

FunctUm  Slack  Description  of 

Ftinctum  Name  Numher  Paraaieters  Parameter 

Gi-HBQl£nahlc  ft29  result  (W)  Interrupt  status  word 

IntSource  IntControl  (W)  Interrupt  control  word 
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Usiting  Character  Device  Initializitlion  Suhroutines 


;  Enable  the  SO-column  video  display  lor  autput  and  Ihc 
;  80  -  co  Lumn  key  hoard   irput  sgbrouljTif. 

VIDED  ON  START 


PEfi  0 
PiiahLong  »3 

PEfl  1 
InitTeKtDev 


jBASIC  device  driver 
;Seliec1:   slot   »3  for  outpMt 


llnitiflliie  output  device 


PEfl  Q 
PuahLong  ^3 
_5e  1 1 rpu  tDev ice 

PEfl  0 
InitTextDev 


;BflSlC-type  deulce 
iSelecl   slot   '3  for  input 


;lnitiaLtze   input  device 


PEfl  JFF 
PEfl  tSO 

S^tQut&lobaU 


;  AIHD  mask  :  do  rolh  mg 
;DR  mask ;   sel  h igh  bit 


PEA  IFF 
PEfl  S80 
SetUGlDbals 


;fiHD  mast:  do  iiothing 
;DR  mast :    set  high  bit 


RTS 

END 


i  Enable  the  printer  in  slot  1.  This  15  eqiiiwelefil 
;   to  a  PR'1    in  the  good  old  days. 

PRIHT.ON  START 


PEA  0 
PushLong  '1 
_SetDutf3LitDevice 

PEA  1 

I  Tii  t  TcK tOev 


1 BfiS ! C  dev ice  driver 
^Select   slot  *■!   for  output 


;TTiltjflli2e   the  ouEpyt  device 


RT5 


END 
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Listing  12-2;    llie  PRINT  and  PRINTLN  Macros  for  Sending  Test  to  the  Active 
Oulpct  Device 


;    PRINT    '  text  phrase' 
I 

■    This    prints    a    line    of    text    without    a    trailinq  CR, 


; Push  pointer  (high) 
jPuah   pointer  (I 
;Ulril*S.tring  function 
;Ti)gl  entry  point 


MACRO 

P»i  NT 

tlab 

PEA 

t  lay^c  i>tl- 1 6 

PEA 

l*sy9Cr>t 

LDy. 

COC 

JSL 

*E1 0000 

BHfl 

eisyacnt 

tisyscrt 

DC 

11 'Liitpit 1 

DC 

Bts/scnt 

AHDP 

;  PRINTLN 

'  texi 

phrase ' 

;  Lerbgt h  of  text 
jThe  text  Ltself 


;   This  priTit-5  B    line  of    text   followed  by  -a  CR. 


t  lab 
tlab 


PeiNTLN  ttext 


t  iaysc  r  t 
elsyscnt 


PEA 
PEA 
LDX 
JEL 
BI^A 

DC 
DC 

flNOP 
riEND 


!  isysc  n  tl-  1  G 
t (ay 9Cn  t 
*S1 flUC 
»E1 DOOQ 
pl^ y  5C  n [ 

I  1  'L: Slext ' 
Cited  I" 


;Pu9rt  pointer  (high) 
;Push  pointer  [low] 
HUritcLine  function 
;  Too  1   entry  p&int 


iLength  of  tsicl 
iThe  text  Itself 


Listing  12^1:    Tlie  GOTOXV  Siihniiitine  for  the  fjO-colunin  Text  ScTL-cn 


1  GOinxv  Subroutine.  Enter  with  the  horizontal  poaition  in  X 
i,  and   the  vertical   pgsition  in  Y. 

jCuraor  horiiontal 
SeOU  iCitr^or  vertical 

DURCH  GEQU         tE7B  ;Cii,^5«r  herirontgl 
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GOTDH 


%8D 


STftRT 

PHU 

DEY 

TYA 

SEP 

LDNGA 

□  FF 

5TA 

*CV 

REP 

LONGA 

□  h 

PEA 

CR 

JAr 1 teChar 

PLA 

SEP 

LOHDfl 

OFF 

STfl 

>CH 

STfl 

»OURCH 

REP 

*S2C 

ON 

HTS 

END 

;Carrlage    return  code 


;Sa\/&  hori^Qntal  position 

jReduce  u-erlical  coordinate  by  1 
;  and  put   it   in  the  fl  regiater. 

;8-bit  accurmilBtor 


iriQTillor'a   CV  (cursor  vtr^tlcal) 
jBacIc   to  IG-^bit  accumulator 

;{do  this  first   to  maic  sure 

i   the  vertical  change  taliei  held) 

vGet   tiori2orital  pQ9itlon 

;Q-bit  accLiniLilalor 


jMonitar's  CH  ^cursor  hprizuntal) 
;CH  for  aO-cDlamn  firmwara 

jBack   to  IG-bit  accumulator 


Listing  12-^!     A  Program  for  ExercisinK  thtf  Text  Tools 


*  Exploring  Ihe  Text  Tools  • 


LIST  OFF 
SVMBDL  OFF 
ABSflDDR  DK 
INSTIME  UH 
GEN  DH 


KEEP         TEXT  tDbject  code  file 

MCQPY       TEXT. MAC  ^Macro  file 


MyCode  STftKT 


Reference  Section  457 


'.MonltDr  zero  page  location^! 


WNDLFT 

GEOU 

t?C 

MtSDI>IDTH 

CEQU 

121 

WUDTDP 

GEQU 

WNl^BTM 

CEQU 

CH 

GFQU 

CV 

CEQU 

125 

□  URCH 

•  570 

video  commands 

njDCriQnfr 

CEQU 

IS5 

riJD  cnpnij 

CEQU 

iBG 

DCCr 

CEQU 

(87 

CEQU 

tS8 

CEQU 

tSA 

c.  u  r 

CEQU 

tes 

GEOU 

»8C 

PD 

GEflU 

SQD 

NQRMflL 

CEQU 

$BE 

INVERSE 

GEOU 

*BF 

SET_40CDL 

CEQU 

f  31 

5ET_aOCQL 

CEQU 

t32 

PflUSE 

CEQU 

%S3 

FIRM.DFF 

CEQU 

5CR0LLD 

GEQU 

*3e 

CCRQLLU 

GEQlf 

S97 

fitbt_j:]ff 

GEOU 

53B 

HDME 

GEQU 

CLGL  tWE 

CEQU 

MTKT.nH 

GEQli 

WDUERIOHT 

CEQU 

*9C 

CLREOL 

19D 

SET_CURS 

GEQU 

*9E 

MOVEUP 

GEQU 

PHK 
PLB 


_TLS  t  fl  rl up 
_MT5 I □ rtup 

PHA 

_nM51 a  r  t  up 
PLft 

5TA  ny[D 
_Tex  t  S  la  r-  tup 
JSR  UIOEn_OW 


Left    edge   gf  window 

Width:  ffiust  be  <-  eO-WHDLFT 

Tup  line 

Bottorr    line  1 

Cursor  hor i zon t al 

Cursor  -uertical 

Cursor  hor 1 zonlai 


Cursor  off 

Cursor  an 

Beep  the  speaker 

Move  ■Cur!f!r  ]e-fT 

Move  cursor  dowr 

Clear   t-o  end  screen 

Clear  the  entire  screen 

Carnage  return 

Hormal  videa 

1  nuerse  video 

Switch  to  4D-column  display 
Switch    to  SD-colLimn  display 
Stop  output  until   key  pressed 
Turn    off   enha,nced    jjd^O  firmware 
Scroll  doun 

rg  1  1  up 
MoLiseTe):!  off 

Move  cursor   to   top    left  corner 

CI  ear  line 

FloLiaeTeit  on 

Move  cursor  right 

Clear    to  end  of  line 

Set   cursor    (BASIC  only) 

Mo\je    cursor  up 

Set  data  bank   ~  program  bank   so  we 

can    use  absolute  addreB^mg. 

Tool  locator 
niscellanecus  Tools 


^Memory  Manager 


jText  Tools 

;Sel  up  80-CDlumn  IfQ 
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;  Just  -for  fur>  lefia  display  the  entire 
;   MouseText    character  ^el! 


PR  1 NTL  H    'Here   15  the  MouscText   characlei^  set:' 
PEA  CR 
UrlteChar 


PEfl  MTKT_DN 

UnteChar  ;ETiable  nouaeTejtt 

PEfl  INVERSE 

bJriteChai'  jSelect    inverse  mode 


Showlcon 


LDft  '"CO 

PHA 

PHA 

_UlriteChar 

PLA 

INC 

CMP  'tEQ 

BNE  Show  I  cor 


;Fir9t  MouseTfct  character 


iDLaplay  it 


lAt    the  end? 
iHd,   so  branch 


PEfl  NaRMAL 

_WritcChaf  ;Splect   nafmal  mode 

PEft  MTKT_DFF 
WriteChar  -.Diaahle  MouseText 


PEA  CR 
_UrlteChar 
PEA  CR 

Ur  1 1  eChfl  r 


GDTQXY  positions  the  cursor: 

LDX  *10  iHonzontalposition 

LDY  #B  ;\/er  t  ica  1    poa  it  ion 

JSR  GQTOXV 

PfilHTLH  coordinate  {10.8)1 


Get.Mod^^       PEA  CR 
Wr  itcChar 
PEA  BEEP 
_U)r  I  t  eChar 

peiNT        'Send  output   to   tSlcrttn  or  [PJrifiler? 


PHfl 

PE;^  1  T  ec  ho    E  he    1  nput 

RaadChar  iRead  keyboard  Input 

PLA 
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Pr  intMsg 


SEQ 

S  h  D  wM  '9  g 

CMP 

'  1  5  » 

BEO 

S  houMs  g 

CMP 

•  'Pi 

Pr  i  n  I  Mag 

cnp 

'■P' 

Get  ^Mode 

JSR 

PB1NT_DH 

PEfl 

Ci 

_Ulr  i  teChar 

PEA 

CR 

.WrltfiChar 

PRIHTLN 

'PRIHTLN 

PRINTLH 

'of  text 

lEnahle   the  printer 


PRINT       'PGIMT  does    the   same  thinq,    except  therei 

PEA  CR 

^WrltaChar 

PRINT        "la   no   trailing  Garrlaae  Return.' 

PEfl  Cff 
_Wri  teChar 

PEfl  CR 
_WriteChflr 


'Preas  ^ny  key  tu  Quit! 


PRINT 
PHfl 

PEfl  SOOOO 

_HeHdChar 

PLA 

J5R  \^ID£D_CN 

sShut   down   the   tool    sets  we  need: 

_Tftx  t  Shu  t Down 

PushUord  MylD 
^flMShutDown 

_f1TEh(itDoLuni 
_TLShutDown 

_QUIT  CSuitParma 


iJSo  echo 

iUlgit   for  keypress 

iSack   to  eo-column  screen 


;(5hcjLild  never  get  here] 
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Qui IParma     DC  I  4 ' Q ' 

DC  JS'lOOQO'  ;Hot  restartable 

MylD  D5  2 

END 


;   Use   Ih^  COPY  directiue   to   include   the  PR1HT_QN  and 
;  VI DEO_aN  Eubroutinei  fouTid  m  listing  and 
;    the  GOTDXY   subrgnline    in    listing  12-3. 
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APPENDIX  1 


ASCII  Character 
Codes 


Characters  such  as  IrttcrS  and  digit';  are  stored  iiisklc  thr  (;si  in  binary  form  (a  series 
uf  Is  and  Os).  the  unly  forui  a  cnmpiiter  undfrstands,  The  i,s  sybtejii  softw^ire  uses 
tht  ASCII  (Amt-rican  Standard  Code  for  Information  IntcrcKanRe)  scheme  for  as- 
.'iigninR  L'tiilracttTS  and  symlxils  tu  niimt^riir  cudts.  hi  futt,  almn-vt  all  microcomputer 
Mjftwiire  uses  thp  ASCtl  standard. 

In  the  ASCII  s^taiidiird,  ench  fharaLtei  is  represented  hy  a  series  nf  seven  Is  and 
Os.  These  hinary  diyiti  ottupy  (he  first  st\eu  hits,  nf  thi^  byfe  in  which  ii  charat-ler 
is  stored.  This  means  that  128  nniiicie  codes  are  availahle,  e]iough  tn  aceuunt  kjr  all 
ihe  printiddc  symhnls  on  a  standard  typewriter  keyhoard  and  s.  few  more.  The 
unused  bil  in  a  liyte  is  usiiallv  set  to  U,  but  ifynu  are  sending  characters  tu  the  lexl 
Sfreeil  of  the  r.s,  it  must  he  set  to  I  (see  thaiJler  Vl). 

The  system  font,  wliitli  QuickDraw  11  uses  when  it  draws  text  on  the  super  liigh- 
resohitioii  Hraphies  screen,  4s:^i^n,s  special  symhnls  to  thr  128  ciidrs  ubieh  hiive  ibe 
high  bit  set  tii  I.  These  symhuls  are  nut  defined  by  llie  A.SCMl  stajidard  and  can 
represent  any  symbol  the  designer  of  the  font  wUhes. 

Thp  firiil  32  ASCII  thijnicters  are  ealled  coiUrut  iharacter-V-  They  are  not  supposf  d 
lu  represent  visible  symbols;  instead,  they  are  to  l)e  sen!  tn  a  video  display. device 
or  a  printer  cuntrnller  to  cause  it  to  perforin  some  special  actinn  auth  as  ringing  a 
hell  [ASCII  code  7.  Ix  Ih,  moving  the  cursor  or  print  head  to  the  benimiiiis  nf  a  lint- 
(ASCII  code  13.  Larritige  returnK  or  moving  the  cursor  or  print  head  duwn  one  line 
(ASCII  Lode  10.  linefeed). 

Althnujih  the  driver  for  the  GS  SO-u>lumn  text  screen  reaets  to  most  cimtrol 
tharatters  in  standard  ways  [see  chapttr  12).  the  QuickDraw  [I  text-drawing  lune- 
tions  do  not  (see  chapter  £»!.  Instead.  QuickDraw  dtlempts  to  draw  a  symbol  thiit 
was  assigned  to  the  code  when  the  font  was  defined.  Fnr  the  system  font,  four 
control  elaaraeters  arc  aisotiated  with  special  syndjols: 
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$11  Open-Apple  icon 

&12  Checkmark  iLum 

S13  Diamond  icon 

S)14  Solid-Apple  iL-oi] 


Other  control  characters  in  the  system  font  are  blanks  or  are  undefined.  (Undefined 
characEers  appear  as  white  qnpsNoii  marks  on  a  black  baclcgriiund. ) 

Thf  following  table  shows  the  slaiidard  symbolii  tbr  iJl  128  ASCII  character  tadtis. 
It  dsn  indicates  how  you  can  enter  each  character  code  from  the  keyboard. 

Note  thai  in  certain  situations,  the  displays  MoiiseText  icony  on  the  text  screen 
iiiiitead  of  the  standard  symbols  for  codes  $40  to  $5F  Sep  cliapter  12  for  an  expla- 
naCiun  of  when  it  does  this. 

Table  of  ASCII  Character  Codes 


ASCII  code 


Dec 

Hex 

Siitnbot  (or  mnemonic) 

Keys  to  press 

000 

300 

>;UL  (Null) 

Coiitro]  @ 

m] 

$01 

SOH  (Start  of  header) 

Control  A 

(X)2 

$02 

STX  [Start  of  text) 

Control  B 

0(W 

S03 

ETX  lErid  of  lest] 

Control  C 

OfM 

EOT  (End  of  transmission] 

Control  D 

005 

.■605 

ENQ  (Enquiry) 

Control  E 

006 

$06 

.'^CK  (Acknowledge) 

Control  F 

007 

$07 

BEL  (Bell) 

Cnntrtil  G 

009 

SOS 

B£  (Backspatje) 

Control  H  or 
Left-arrow 

009 

$09 

HT  (Horizontat  {abnlutiQii} 

Control  J  or 
Tab 

010 

,^0A 

LF  (Line  feed) 

Control  J  or 
Down-arrow 

Oil 

$0B 

VT  (Vertical  tabulation) 

Cnntrol  JC  or 
Up-irrow 

012 

SOC 

FF  (Form  feed) 

Control  L 
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ASC/1  code 


Dec  Hex   Symhiri  (or  miwmpnic)   Ifieys  to  press 

013  *0D  CK  (Carriage  return)  Control  M  or 

Return 

014  80E  SO  (Shift  out)  Control  N 

015  $0F  SI  [Siiitt  ir^)  Control  O 

016  $10  DLE  (Data  link  escape)  Control  P 

017  $11  DCl  (Device  control  1)  Control  Q 

018  $12  DC2  (Device  control  2)  Ctmtrol  R 

019  S13  DCS  (Devicp  control  3)  Control  S 
ceo  $14  DC4  (Device  control  4]  Control  T 

021  $15  NAK  (Ncgiitive  acknowledge)  Cnntral  U  or 

Right -arrow 

022  ?16  SYN  (Synchronoui  idle)  Control  V 

023  ¥lt  ETB  [End  trdnsniission  hlock)  Control  W 

024  $18  CAN  (Cancel)  Control  X 

025  819  EM  {End  of  medium)  Control  Y 

026  «1A  SUB  (Substitute)  Cointrol  Z 

027  SIB  ESC  (Escape)  Control  [  or 

Esc 

OaS  *IG  FS  [Field  separator)  Cantrol  \ 

029  $ID  GS  (Croup  separator)  Control  1 

030  $1E  ftS  (Record  separator}  Control  * 

031  51F  US  (Unit  separator)  Control  _ 

032  $20  (space)  Space  Bar 

033  $21  t  Shift  1 

034  »2a  "  Shift' 

035  $23  #  Shifts 

036  S24  $  Shift  4 
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ASCn  code 


Dec  Hex  Sijmhol  {or  mnfmonic)  Keys  to  preax 

037  S25  %  Shift  5 

03S  S26  &  Shift  7 

039  $27 

040  $28  (  Shift  9 
IMl  m  )  Shift  0 

042  $2A  *  Shift  8 

043  »2B  +  Shift  = 

044  fi2C 

045  S2D 

046  $2E 

047  $2F  /  / 
(MS  $3(1  0  0 

049  $31  1  1 

050  S32  2  2 

051  S;«  3  3 
ft52  434  4  4 

053  $35  5  5 

054  $3(j  6  6 
0.55  !ii37  7  7 
O.Tfi  $38  8  6 
0^7  S39  9  9 

058  S3A  Shift  ^ 

059  S3B  ;  ; 

f)60  $3C  <  Shift  , 

mi  $3D  -  = 

[)fi2  S>:5E  >  Shift  . 
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ASCII  code 


Dec 

Hex 

063 

S3F 

? 

Shift/ 

064 

$40 

@ 

Shift  2 

065 

$41 

A 

Shift  A 

Q6fi 

B 

Shift  B 

067 

C 

Shift  C 

S44 

D 

Shift  D 

069 

MS 

E 

Shift  E 

070 

F 

Shift  F 

071 

S47 

C 

Shift  t; 

072 

H 

Shift  H 

9149 

1 

Shift  1 

074 

1 

Sliift  ] 

073 

$4B 

K 

Shift  K 

076 

Iff  » 

L 

Shift  L 

C77 

M 

Shift  M 

078 

$4E 

N 

Shift  N 

n7n 

y  1  *T 

O 

Shift  O 

080 

$30 

P 

Shift  P 

OSl 

$51 

Q 

Shift  Q 

082 

S52 

R 

Shift  R 

$53 

S 

Shift  S 

e)64 

S54 

T 

Shift  T 

085 

$55 

U 

Shift  U 

086 

$5fi 

V 

Shift  y 

087 

$57 

w 

Shift  vv 

088 

$58 

X 

Shift  X 
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ASCJi  code  

^^'c   flex   Symbol  (or  mnemonic)    Keijs  to  press 

UH9  S59  Y  ShiJt  V 

090  S5A  Z  Shift  Z 

091  «5B  [  [ 
tm  $.5C  \  \ 

093  fi5n  ]  J 

094  S5E  -  Shift  6 

095  $5F  .  Shift  - 

0%  mi 

097  Sfii  a  A 

098  562  b  B 


c  C 

100  d  O 

101  SG5  e  K 

102  m  f  F 

103  !!;fi7  g  G 

104  .'Sbti  h  H 

10:5  m  i  I 

106  $6A 


j  J 

lOV  SfiB  k  K 

108  «6C  ]  L 

109  $6D  m  M 


110  SfiE 


n  N 


lU  o  O 

112  $70  p  p 

113  $71  q  Q 

114  S72  r  R 
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AfiClI  code 


Dec 

Hex 

Stjmha!  for  mnemonic) 

Keys  to  press 

lis 

$73 

s 

S 

116 

S74 

t 

T 

117 

$75 

u 

V 

US 

$76 

V 

V 

119 

$77 

w 

w 

IW 

$76 

X 

X 

121 

879 

y 

Y 

m 

5VA 

z 

Z 

123 

$7B 

{ 

Shift  I 

124 

$7C 

1 

Shift  \ 

125 

87D 

} 

Shift  1 

126 

S7E 

Shift  ■ 

127 

87F 

(rubout) 

Delete 
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APPENDIX  2 


The  Western 
Design  Center 
W65C816  Data 
Sheet 


CMOS  W65C816  and  W65C802 
16-Bit  Microprocessor  Family 


>  Adtf-flnCAO  CUPSdi^gn  'or  la*'  paw*r  cr^iurr^plion  atvi  incrsBiH 
noi»  iiFimunily 

"  EmuiEii'Dn  maae  audwv?  tump**]*  nirdwjhr*  t^*irii 
CDniuaNBiiiiy  tinUi  ^oiigni 

■  Pull  E&  Fiii  ALU  Aiccunauialcr  SlacU  Frknier.  and  Indfi'  Rtgrir^r! 

>  ^■'dlllII[>ELL&Ad4ri^fi  |v'r>AiancuiiiiaPrc^g<im  AAd^^s  jVPA^aurcLnL 
aliwE  dual  r4cr«  ana  crcif<  ai&ru  UWA  i  ifipitrYiAriiAri6<-i 

VkIpIJ  PjJI  IVP^  CulpuE  indifALM  vPf n  inlDirupl  vvurQi^  mrn  bqiriQ 
addrtHH  Mitji  at  uu^  ici  imfiliirnHni  upcinrvd  mf-irruipl  dHigin 

■  Jtoar  (ABQRTj  irfipul  ind  asiocdlM  VKCor  luppdMi  virlLiiltTiBiTiarY 

"  SepiratB  prirgraiTi  Jirifl  diia  bui^k  ^agiiEe-tt  ■iiait  ^r^jr^nb 

H^mc-nrm-l^n  ■>  1u.ll  1&-WH^ia  UPcm  ^ddrvumg 

■  MeiMCi.rpri  Ragiiiarvni^  irjic^  rBliliVfaddreHiino.pravicHfcaf^ilrry 
irjr  riMjnrrani  r*  zumtm  ana  r*-iDcalinw  p^aflrirriming 

■  ^4  iruresftinf;  'nodas  — 13  vi^inal  BSD?  rh^^m,  plus^  11  new 

'  N^vt  ior  \n\t!/-up\  (WAih  an^  sro^  rhA  •Qifick  i^TPj  iRiirucriDni, 
fur  W  rBQuHifl  power  conaumiprion.  dnrnHH  inr^rrLpi'  LUirviy  ind 
allawa  "ayrirnrDniMiifin  wiiri  iiirivnil  irk<Hnift 

■■  Mm  Cn-F^rcTHiinr  ii^iirvclinn  ^COP^        asiof  larH  -^Klor  lup- 

MBtA  DiQCk  TiOVfi  dBili.ly 


Ovfnral  DvKilpUon 

WDC  i  W65i:a02ana  WSSCeieanCMOS  I^D-r  micr&procflMori 
lurvigiaiiiuir-tirB  campflrininry  Mrtmiriflir  a-ui  rcwos  hnd  HUaS-EMCh- 
wiH  p^-Mef  fruordi  Tnfi  W6^aa?  is  pin-io-pin  c  crrvpiiibiA  H>tn  fl-Qii 

dAvitn^i^un'nAlIf  rivailJLale  «MrvilD-rnfl  ^&^Cai6«-ilntid4  iddi'^ii^Q  lpQ# 
lull  IG  mRBabyivi^  Trun4  davicM  nifBr  irv>  mnny  aDvvniigdn  CUDS 
iB[:nnoii:>gy  mcluiding  incrBasAd  noiu  jmmuniiy.  nigriar  riNiPinry.  and 
O^aally  reHucad  povi^r  rBq^jininiiinCi  A  B^hircn  dflEBimtnH 

wridirviT  ine  prtuauurM-  li  in  me  B-bii  'e^iJiaflicin"  moa^  m  1W  nirivit 
mooe-,  mug  aiiawin^  e>ihririg  ic  uu  Ln?  fi:ipii'^dea  r^aiurM 

*«hownin  lhe,t]r«mQipivgrflrnmiJiQ  modflM^Acturnuif  Idl^LU, 
K  and  f  indat;  reglBl«^.  end  Slack  P-o\nlv  regni-lBr  have  alt  b«n  sk- 
landed  La  BiS  bila  A  nan  1G-b"tDlJ'BcLPa9e^egllS'lfl'alJ^)man1alhfi  Dir«1 

Ptf^mm  Binkantl  [>4li  Bank  irg^'vi  ^ll^'^Z'l-bil  mumory  iddmi>nQ 
m^t'  BBqin«i>l«4  or  lin«r  idtirVHIOQ 

Fo-ur  nnw  i4gnAli|]rflvi-dB  Bh-a  a^Bilim  deBign«f  rnany  aplinn&  Thft 
ASOFbT  incul  can  mmribipl  ino  currvnil^  aPKUlin^  inslruclLan  *iir>DLr1 
miH^Vinpinliifiiil  rsgistni.  rliji  jDlp-nLn^  uinuBl  nwnorv  t/itsmiMtli^n 
v'fliid  Da^i  AddrBufvDp^t  jnu  V&wa  Pingram  Ad<[]re^g  cv^PAi  ouiEn^m 
lBi:iii[BLe  dual  m?hfl  HQmory  by  irdiulin^  wnBinef  a  dalB  KgriEnl  or 
program  aeg^nar^l  is  aLCOsaed  MudiEyiig  a  ^aclar  13  rnade  aaBy  by 
meir>iEaiirig  ^ha  Vnergr  Pull  I'l^P^  Qulpu^. 

note       iv-iBi  rne-  dmgn  frngmMr.  j  Caveai  anp  Appiiuiicn  Inlw- 


Wfi^CAIfi  ProcHur  Proprantming  HchM 


tftpTa-      1       laiTs      ■  iBrr» 

□ill  esrik  Reg 

(](ni      ij'  ^)(L^ 

'~Di[B  Barb  urn 

IMFil 

fnagarwHi     J    c  Hagalv  Low 

(VH>        '1'  (YD 

r 

at 

^rjHk  ftagiiiiH  Mi..!,  sua'  uta  \,a* 

(srn       1'  (SuJ 

\--f601 
1  '  f*BBH»™ 

<ei      f"r"  1*1 

Prnoiim     .J,,  Csuntv 
(PCkI  (PCLi 

00 

Ci'H^  H'sg  Hi  ,i  Direci  Pi«  Lm 

SWluHaiilBtof  Coding 


SWLJSflEG  (Ml 


U  \  Ul  %  o 


TEBQ 
"-OECIUai  MODE 

i-MEuOBvatLEcr 

"-OVER  FLOW 
l-NE.G»TlirE 


-BESUlT  ZEnO 
-  TBue 

-BBITO-  ISBJT 
ISB'T 

=  THue 


Pin  Conllgunlton 


Ml!  It  ll  Is  'if 


>  *  < ! ;  1 1  ^ ; :  J 


I « I B 1  i  i  e ;  1 1 


t!psk.«aiiiii.a 


e 

fat  notM.  rvMr  tn  ^ekiQinfp  IniormiiElon  Fwcl^nn 


Drngn  friqinm   ^.liimfl  ktai|i]h  /) 

I  THE  WESTERN  DESIGN  CENTER,  INC. 


AdvanCn  lntorm»lliMi  DatB  ShMt 

This  ix  advHrc^d  inlormation  and 
Bt^eClfiUtlona  are  subject  to  cdangB 
tvithojl  lollcs. 
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JUhoIuI*  Mwdmuni  Ritli 

>Si:  (HM  1 1 

Symbol 

VBH 

-0  JVI(>  -TCW 

In  Hit  VplU<B> 

-D     lo  Vdd  'D 

ap4ririn<g  TBrrpa>'iij^d 

fl'ClQ  -70"  C 

eidrj^a  Terrtparilkirfl 

Tb 

Piirinirlv-r 

Sgrnibal 

MM 

Hbe 

Unll 

Inpul  Hign  tftrttagB   

RES  BD»  ihO  □■ta.  SCj  nt 
«:         IslMI  ABORT 

VIH 

9C 

a  7  voo 

Vaa  -  0.3 
VaB  •  0  3 

V 

n~E!i  noy  'Fio.  □■».  so  'QE.. 

UIL 

-&a 

as 

03 

■J 

V 

jnpui  LAliiiM  Curriani  i^fv  -  0  (□ 

nui.  img.  sp.  be  abOhi  ;ini*rrui  iviiiup) 
i1Dy|l■l1BT^■|lPull^Jp  oeanoiiini 
*?IIM1  _ 
Addrni,  Dati,         (OltSEalF,  BE  -  Ql 

IIH 

ISO 

i» 

in 

1 

uA 

OjlFMJtH-gr>  ^Dllld*  |lw  '  -laqii*! 

SVNC.  Dan  flfWr™  RiW  Ml.  VP  MM  £  VDA.  VP"., 
i^t  laUTI,  «Z  !□□![ 

VQH 

V 

Oulp.Nf  Low  Vollage  ^IQL  "  1  timfti  

SYNC  IHHU  fiaaiesi.  am  ml  vp        E  vDft,  v^A 
*i  lOUTi  fa  ioui| 

V 

Supper  C^r-eri  iN^Luad^ 

* 

■nA'MMr 

Slardbv  Cuiignt  (No  Lwd.  Data  Bu9  -n^Bi  upp 
RES.  NUI.  ino  SO.  BE.  ASOnT,  «z  ^  VoQ) 

w 

CifHCiOnCS  fV*.  -        T»  :  3)"C  l  :  i  WKTJ 

Addrtu,  Dau  R/Mi  torr  siaiej 

Cm 

10 

11 

pF 

P4FI  Functdi  Tibit 


Pin 

HO-*  IS 

K 

Bus  Enanlfl 

Pr^p  ^  In  CiaLM 

Ml  4DUT1 

"hMi  1  Oul  CIm* 

•  i^DUTl 

Dh.)f  ;QuI  C1«Ii 

DO- 07 

Qiia  Bui  [Ge^Caibt 

DamB.i  MuiiijjioBa IQSSSCaift* 

!  E 

IHD 

IntiFr.ijpl  nfgMMI 

0U 

Mea»  SaLMi       iv  .P>) 

Ma 

Dnoipnon 

MC 

Ha  Cdinnmiion 

HHi 

Nen-WahabiB  Inbsnuift 

RDY 

Fiiii]''M'iia 
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Furvclieviji  DpM<:7tp|ion 

Jnm  WfoCaOil  orrpii  ihm  dr-K^gn  pnfli"&Br  Ifvp  upparibkmty  la  ul*liZB  MiM 
mating  ADHiwdiv  pii.>g»ami  tn^  t^rdnBiB  toTiriaurjirnnB  vrhiie  Al^n 
■  Dnieirin-a  ih"»iJ^BiJaO*di|Hfleaorintr«tBaregmBr  lengnn^  Binal«ier 
flflfif  uiPQfi  rimi™  rh»W65CK>3i  m^wa\vm  dBiion  una  imciamBnia- 
Non  FiBrurHB&roiTPafl  rn*  dv^i^n^i  incraiaiialiDnic-iiiry-ana  reduced 
implflinsAterifln  Ci^l'*  ii  iha  ETiuijifor*  mMj  if-p  W#k^-Caaj  fici  aniy 
nlliifi  EarriAbrv  wmoili-b-l'li'.  bul  n  aIsq  narnwar*  iDi"-lo-riin^  com. 
f,n\\h\e  viih  §MJ  designs  plui  n  b*imopb  ine  A.uwflnL'bQB^  rt\  le-nur 
.m*fn*i  opBralnno  in  EM?-^timpii.tjie  apcl'CiLiOfit  Trie  WSSCMP  li  an 
VHuiivni  ddracl  rrifklACvn-ivn^  mitfDoratmsar  for  flSOJ  aeiign-i 
Trs»  ^e&csifi  oro'-iiM  iha  ijg^iqn  vngmeer  -fn»lh  up#ara  nconiLy  a<^a 
Vtiivitn  cnmpaliOibiif  on  'tpri^^licna  wfieiB  a  1'B-Cfii  sviCBm  Eunrigura- 
lion  15  DMnrM  Tn*  SV^MiB'i  iS-Dii  hard-wflir  ccnHi^uralion  ccupWO 
wilH  curr-eni  ^oliward  oiicwi-fi  thide  tfiifrLiig<n  ijl  jvsl^i^  -app^icairong  In 
(ne  Emuldiion  mod*  ins  ^SCSie  gl<t-s  many  advanugoi  .nBiuOinp 
FuIlip«i«arpro'np&[iBiilir^*i1ii850?i:iJdi'>B  Iniddn^tin  ihsWeSCft^fii 
pcpHui  in«1iuMidh  iQi  and  adiJieam^g  muiJBt  make  il  an  eaf«ll4Tii 

klimal  organiraiicirT  □■  iplp  W5^S£12  dnd  w^gC4iij  can  ix  divi^^ed  mio 
irmpariB  l j  Khp  RuflisEer  Swlpflrv, -n<J £)  ri^p CljhiIioI SecEiori  lni^«ijt- 
Imna  ^or  occnpiseil  chl^-ned  lium  i^-ogrflm  iriflniarr  aio  piKrulad 
irtiplBnvjnim^  a  iStiM  ui  iit\a  liitn^rprE  tvuhiin  inn  E^bqi^ivi  Setlion 
SiDnoltindi  cau-^f  aaiaip Bnii«f«  tah6  &piHu»d  orv  g«ngraEe<d  wiimn  ihe 
ConUD' Sefimri  Bnin  iitia  Vrf&SCafl-J  and  rhv  WS&CHiS  ■  tB-tin 
ir-Lernai  ireh«Pcrur*wil"jr,a-Bil  aiticmiii  ijiii 

InalFuetJon  fta^jitvi  ard  Dac^d* 

Ar  cpDDOP'eniE'B  ["e  procp^sor  on  |hs  Dili:  Bu*.  omj  i»iiBl:thQ4 inio  lha 
InirrifDNon  ile[|iiiflr  d  jrinQ  mgirirfhun  Ivl^h  c/tiB  Thki  inalrutiicin 
i5i»»Eniafr=jdea  jigng  rt^tTni^ming-nc^  intsr'ujjE  ii^nala  IcganoiBrBms 
vir-au9  ln»|rkjcl<an- A^i-bTAi  CQfirrgl  iignaxi 

TlmEng  Cnnlf  cH  Unbl  fTCU) 

rtiE  Timing Coniro*  u mi  ket-pt  rrac*  ol iach inifruchdn  cydp  ai  i1 1  & B'- 
ncwfird  "i-p  rCUia  mi  ed  ibfs  ?Hh|imeaf^inilruf  iignlnipi^h  ite^ecvl«j. 
a^LJ  HQ  didvancea  ai  Ihu  Qigmning  or  AAcr  f^^'a  fij*  aa  mdnv  cvLin  aa  ■> 
regut'ccl  CQmplBlB  irtp  inalFurti-on  Eatri  daBa  lFanaT«r  rwMMn  r«giv 
(Er-B-dBCFflnai  ucunflPGoamgiriecDniflniicirBoinine  in4rruciii?nH»fliB.. 
ler  [inLJiheTimmpConlJDl  Uni[ 

ftrtlhmalk:  and  Lc^^C  Umt  (ALUl 

All  trilhrn^Nc  and  itjQit  aDQraiiigr^s  riUfl-cHatP  H-thin  irifi  1firb,i*LLi  In 
Hd.|ii>nio  4i  ij  □t«rdEiori«.itiBALUai5Dcalcuiatp«  miiellftc^iwaa<1dW4 
''Or  rvliliiredFid  indHw.Ed  vdO^rmaiFtg  nuciH  tfib  rwiwu  o-l  analaap^r^iidn 
-a  irorM  ih  tiiPiiPi  mBmory  cw  aninlBFnal  roflJBlflr  E^rr^,  Nt^ii^r  O^i 
HQi»  arid  Zero  iPaut  mdy      upffiii?  FailawiFig  IJ^e  ALU  Mtni  opBr^ingn 

ilnlamjl  Rtglii<n  |Fiflt«--ioP»Qqrarnini-iB  MmJBl] 
Accumural«r>  [A.  B,  C) 

Tn>e  AeeumLlaa^ir  n  fi  Qfvrisrai  fiu'paiA  r^gcpiti  w^p^h  Btarea  u^e  dI  I  ha 
ojneranJi,  ur  iF>r  pbiuM  ni  jnoii  jJilFfm^ipi;  a^^J  logical  acwiaiiona  Imna 
NdLive  Tfiufla  |E^m  Ahen  int  Adti^iFTuliior  Ser-etL  Qil  tMr^u«-lb 
IhE  Actumrjiasor  15  f&Lfthhe^n^  4i»  Ifr  bils  *iiJe  lA  -  3  Cl  Whsn  irw 
Aecifmijiaior  £eiMi  a-r  [M|  qquila  one,  ih*  Accumuaanji  ii  fl.  eh[&  wiM 
|A|  Ininiscas*  ihr  pippcr S QitB  |Q|  ma^ bn uifn^ Tgr Ib^fipd'aiv alora^ 
>n  rDPiunciiun  *nn  !n*-  E-cMjng*  Atcumnliiigr  {HBAl  inaiFLCiion 

Bifik  Hvpialar  (DBfl^ 
Dur'ng  mcdn  «F  cifMraii^n  ihie  B-bil  QaU  Gazi-ik.  Hvg-ilBr  Nolda  Bha  da- 
laultbank  Kjd''BUiD4imenior>lfBnBf6v-a  Trwf^-cnatfdruaiiraniipaMd 
□r  the  lO^bii  iffiBimciiQn  Hiieri»B  iddrni  and  rne  B-bii  Daia  Sink  m4- 


ara94  ThoTBgiti^r-faluara  muhipMiqc]  viihiinfl-iraia  vaiuB  ansqpmani 
on  na  Data  Ai1<3rei*  lin«  a^u  n^ihe  l.rat  half  of  j  dn-ia  uanB^BrmamorY 
Ci^rwrfKih^  WEsg:si^  ThflCJalaBan.li  Rasa\aii%in.r\eviaaia.7i:ioauf- 

nrvQ  FiddM 

Iht  ifriMr  Difpc-r  nagist*r  prouia*s-"n-iJ.d'«a'D/rs«Ht>r  all  inirucBiDns 
uiinfl  diFBCi  iicarfli.i>n9  Tn««llQchvt  Dank  lero  adureaa  la.  (orma*  &y 
add^nfl  rna  a-rm  inii:fi>i^iie.n  opBrand  a4d''«al-s  iho  Uimt  FLsgnter  Th* 
■D.recJ  r^ftgis*^'  i*  .fli.hialind  is  iflro  during  Riio^ 

TTiBrsarBlwolnOe.  PAgiirHrc  fjl  and  V|  wh»ch  "Uv  he  iiaia  bb  flsnpn-al 
purp«wr£^iirfra  or  |e  p't^wndi  an  uiQeB  taFua  lor  tJ<culiiEian  n<inB  PF- 
■IflcrivPitfarMij  ■^'i9n4«Hu(i"g  an  iFtalruciiDn  wnn  indBmoaaaFeaajngi, 
irvt  mitrapiitPtimQi  iBlciwb  opc^dB  nni?  rfia  ifats  mO'EBi,  jt^d  ^r>&n 
mo^iiriBs  ih*  ad-dftHi.  0^  *Oflin(f  inf.]ndQj^  Heffiatercorlansa  Eo-Ehd  ad 
dre!.5  p^ior  ro  ^rarrnii^Q  ihf  tftnirBcP  opBraho-n  Prc-inaBiiinh^  jir  poal- 
inflaairi^^irnO^rBtratfdrmaesrnar  Ma-tlBcBnJ  In  ins  halnwe  moda  CE^DJ 
hci[h  inijaB  JTagialera  are  I5  biEa  wrda  iurgvdpng  ine  >naeii  ^lecr  Bir  \,x\ 
■quj-lH»ra}  "  iha  I  nc^Bi  Sp<BCK  BfM  aqual  B  Dna.  DciEh  rtgiaUBFa  will  m 
I  Qit*  ..'iSb.  *n^  ]hB  hiflh  bylB  IB  'oj-cBd  La  laro 

Proctuor  fiiaiuH  (Pj 

Thp  B-On  P'i!icfih^i  Sld'i^)  FlBgrp^Bicun1ain9B[atuiriigsaiH3  modeBfllBCl 
bill  ThfCifiTCCl  r^Bil've-^Nf.O'BFflaM  i^i.jinijrBr^  ilialal^a  riaga 
rvfia  rnpnn  in«  irArui  or  mfpfrt  JkLU  atArJUiO^ip  'Pih^Qps  aldlua  flaganrB 
iBtlfid  ^^  □)  CondiiEional!  SFHn±n  mflnjciigns  The  lOecirnfli  (^l 
OlbbOIb  |I},  We-riifii>^4«,un=uin[cn  B'^lJ  If^Cbji  |W^  Eiia  aip  LitBH  at 
fnodfl  wieel  Uiig^  Thm  ll^gi  iig  h|  by  the  grog  lam  EOthange  miCJO- 

The  tmuiaiian  »iiici  ana  rris  araaA:  |B|  fUgg  h^b  aEceuiDie  onty 
EhFDuaFi  rhfl  f  FocBSSor  SflaBiiS  Fl«giitfir  Th^  ^rnu'aliQn  ^noLJa  a«lBLl  Nag 
iaaBlBclB[Tr>jinflE.cn.BngtCaHy  j^flEmijiiflCion  B«ta  rXCE)  iniiiutnan 
TablB  >  WSSf^DD?  ahd  SV^SC^AIg  ivtoi^  CarrtpBfiurk,  irlu^njiBi  (hB 
FsaruFei  rnt  NBh^n  iEtOJ  ino  Emuiasi-nn  |E-ij  msiij^  JnB»/  anffX 
liaga  are-ntybB^?  pqufi  Caona -n  inc-  EmuUiidi^  fthiQ?  Vftt^n  an  ifi-Lerrijai 
occurs  d-jnng  [he  Ei^iuLnliQ-ri  iTiiVli  thb  Brfljiii  Nagi  i»  wnLLen  1:^  auck 
momary  m  bd  I've  P'ac^iAO'  Siaru^  flvgialBr 
Pruflram'  Danh  RtpWtf  ^PBRJ 

Tt>p  a-Esii  lOrijQum  9jnh  ftflgiitier  hfliaj  ^h*  Dana  jorl-r«u  \of3l\ pn^-lruf- 
tiijn  rHjiiJ^et  Tri?j«-QiidddraaBconaniUofirfl  iG-bdirvairBfiiiib.^HEijtEiTff 
add'c^a  an^J  fl-bni  Pi  Dgrani  Hanikadflrpaa  7  ha  re^iiiDrrplvB'B  "nL'll- 
□■-ff^fld  withlr^daEkVBiuBa'H  DrgB^rHfaoAihA  [>AmrAdd«nBlinHdunnf 
lMb  '11 91  njii'-g'  aEMoyr^niinfrniDry  UfAO  ^rla  Tna  Prcgiram  Baiik  H^if- 
ivr  11  miiialhieo  Ic  iBtn  during  l^aui  Tna  Phh  inairLrftlon  p^dhAH  tht- 
-ogiftLPi  arlQ  \Ue  Eiaek 

ProVfin  COUrtltr  (IPC) 

The  14-D-it  ProD'an*  CujmBF  RBgi3,ivi  pruwudBame  adorf  u«  w-hicn*rB 
uaed  la  al:e<Q  lr>e  miLrap-ri^nKii  irucFugh  BflQuenNal  7iri:^Fjim  micru^- 
<»Dpni  Tn&  I  pgni»r  i a  nc"* mn n  1  aS MCH  liPM  BH I fH Eivci lo n  OF o pp ra nd  la 
l^ifhrf^  I'Dm  pr^grfrn  Tr|Q<nc^rY, 

Tr.e  scfttk  Pamr-cr  ig  a  iS-tji(  rvgislfl'  whinh  it  uiBaa  co  maicdie  irc  f-pni 
a^Aplifild  locBti-jn  in  ihe  ilack  n-isn-i^Hy  i-ib-i  li  ao'i^vt  at  li^BfllTocVvfi  Bid- 
drcjiin  Slack  BJlfrreB4ir,gmMl*4aB*,|ia»-iubrsuBinpaj^d  in»rrupi  pro- 
WB4infl  Tri&Siafk  nQiriEHnlliCmfti-nplairnplBnaFitanonH?!  naslMauA- 
rauiiri&4  and  jnvHiplff'iwBl  iriLBrfupbi  DuTing  lIib  EmuiflUnn  rnode.  me 
5lM«Pqinta>rhigri-arclarbT^tt^SHKiBaivrBVBBauaMaana  ThBbankid- 
drBH  lor  air  rIuIl  apAiBiiqnt  i|  Ba/i^.  tvOr 
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Flguia  1-  BIOCK  Dligram  —  Internal  ArcMlaclur*' 


Signal  Oetcrliplion 

r^e  (oiiowno  Sifjn,!  QascjQliQn  BDRiiFt    t*"i  ineWBSCSOB  ana  me- 
^SCBltoarecl  3!^  oihnnBinB  naiad 
Abort  (A'BOFIT)— W6SCS1fl 

Tht  Abaft  ifkpijl  IB  UB«4  tg  fitKi'i  irikErumariB  iLiiuf  riy  flue  m  dr  ^dciiw 
Buicondilitmi  A  regilim  ir«in.rinH  "i"  ijirvinir  mooUHMiiiw  ol  ant  in- 
»™l  rwiiligr  duiing  the  eL-ranl  in.,iruei»ai  Upcn  complBilon  M  inii 
Inalnicuon.flJi  hiIbtupI  aequerns  la  in-itinFBd  The  localfcon  oi  1Kb  abariad 
opcoOi  ttilDrBtPM  »w  'alMrn  addrau^n  B^ii:k  marfiof^  Tub  Mwrt  flCWr 
»oairBMtt'0CFfP9.»lErT'uij"iJ''  riLad»|  di  OOFF'Ee  3  |PU1n-B  mwUl  Mola 
lh.li  *BOHT  II  a  pulsB-aerwlim  vqn«,  it_,_ir  jBort  nccui  mianBirei 
mBniii.B  niffstn-c  pulse  nHie~sl|iffnifi»*HOB'  pindunng  iiifrlvBi 

Addraaa  Bui  (i(0-A15) 

TneiB  !iHBBn  1JU10U1  ItumliiB  ftiWi"!  Bui  loi  mBmmy  BnS  l;0 
•  icnirige  nn  iriE  Oala  Bu>  Whan  usirvo  IWWBSCeiB,  MaiBi*  Imii 
miy  b*Ml  ICPihB  high  imH^ano  iiala-ev  mi  aui  Enrnwr      )  Bignii 


Bui  En>U«  |BE|— WBSC^K 

The  But  Enji^i^  ii^'pul  signal  iiin-in  BiFBr')iil  rcntrofl  v1  mi  AddrsH  ir>^ 
Daia BuHais. a* ** in* H'rt !i-(]nni  rtirn  aui tJiaci! niBh  thiaB.W 
jriO  Addms  BurfBii  irr  bciIvb  Thf  Dali.'Aaaii-»  ajKert  ira  iiLU'e 
ourirtB  ihB  liritlia]!  uleniry  tuSl^anD  lhf-s«iDnd  njH  01  iw>ilacvt» 
WntnBE  19  Icn  [heiBtiurr?nBiodiiaB'™  Bus  Ennhiaia  anaivntJiip- 

nous  5"BnflJ 

Oau  Bua  |DQ.0r)-WBICBD2 

HinmgMI  Cala  au*  l.nai  piuviiie  in  e-b-l  PuJiriKlhunsI  Cala  Bu»  ror  uw 
-during  4piB  dKfran^BE  EMIMwn  cha  rnn  rocm**!*^  anff  e  *lirnai  friim- 
wv  or  iMiiBii«'"-l4  l*c  raflmtHV  r¥=»s  are  lequirnd  l"i  m*  Irans-lir  01 

16-Bil  «fllua« 

□■tB/Addraii  a<J«(OD;BAa-DTyaAT>— We^CSK 
Thweiahl'inecTiuilictEiaaarBBaDilsB^-^ATiribhilhidal^iilua  The 
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Adami  n.pfMBKldginnHih.jlirBl'hBll  1  mamniv  syelB,  ina  IKp  OflU 
■  ai'ue  n 'Bud  111  "iTinontiuriiiglhEMeooidhilFEFIfHTHjrary  cycle  Una 
nutnvQrv  tyc]^^^:^*^^"^^  lD1iBnar«r  Tfl-on  vium  Tnawlinaimay  bn 
HM&  ihfl  h-g'i  Tipedi-^ce  slAifl  Dy  IMbBlji  Enan*  iBEj  iigrui. 

EtnLil*lJ(in  Sana  (El— wascBiB 

Tnt  Eiii%.l«ran  Sitiloi  C'jtBii[r«ifcfiaif,»5iiiflol  hhe  EmijlBliar  (Elmsda 
IIBgiinirBPiocB55fn&[i[ij*<P|  Flrgifl^r  ThiB  jiaralinB^bBilioushi  at 
Mtmn  apcace  f<xtbriiia^  mnd  iwnJTgr  mBmarrBfid  H.v«L«rTi.inpn*HBmHnl 

IrlHTUPtflMJIMBl 

TnairiisrrMDI  i^«]u?5[  m.girl  signBlii  u»d  Ic  r»qu«atllu1  in  mllnuDI- 
HquB-riLs  Da  I  nil  laieci .  wn-sn  in<  IRQ  Oiibdib  (I|  Ijbq  i  i  fiaBr*^,  ■  liyn  I  n. 
Umt  iD^lt  iBSCi  inpLiBDna  on  inlHrrujjr  iequ«ncfi  lina-r  IPh^  cu^rtnl  inglEuc- 
tlon  a  compiBied  T*\a  ff^ait  fcr  ini^rrupi  *i«Ai:|  iviiiTudiDn  Tiai,  be  e«- 
ecutad  tD'firau'emiFiniBrryjji  yfiiniBr£Cflg.nijoa  ijnmiidnrely.  ri^pintef- 
nipt  Paqueai  Mnaioi BOOrBBa  la  DDP^ r  fEmu.n[|on  ma»|ortiOFf  EE  F 
[Mliu;  mq^ej  S'nte  IflO  iij  louol-wfii.iiwc  .npul  an  .n1&ru|5i  win 
CCEUT  >r  ^hB  HniQrr^pf  lource  hu  rni  cte&rBH  stnca  ma  \jtfr  inrtpn-upi 
AIbd-  rw  mEBr-rupE  will  Gucur  it  mleirupl  Bourrn  ii  clflvsn  pncr  Ic 
xnlHrrutJC  friDgnliiijn 

Mamari  Lock  IMLf— WKCBie 

lFi&  MarTpfli^  LQi:^  ^yipul  may  ti>e  uuid  lo  anturs  ch«-  iniagnTy  ol  '^d- 
MMiH-Wriiff  iritrifci-.ijn.B  .n  i  ti wlllBimftHor  iyiiBn'  Mamory  Lael 
iiaiCtfjB  l^s  nwO  Id  i»ter  I'blljitlan  et  CIib  iwil  hiri  cycle-  MBmorj 
Locliu  lowOufing  ineiLinlirH  5''l''S  sytim  af  ASL.  DEC.  IhC  tSR 
POL  flon,  TRB,  an-fl  15B  mnnio'^refarentiflg  insvutlipf^i  aapandinQ 

Hwnoiv/lndii  SbIki  $u||i|  |H/II|— WUCHa 

Tnti!  muiEipieR^-a  s^uipiui  i^Ugcie  rhe  Hiale-  ol  ir«  AtcuimjIaEor  lUi  aid 
InDfii  ixj  ieieti  nag*  {birp  ^  ana  j  t:n#  pi&ch^i  sialus  IP^  R-e^iiLer 
flAg  Mflfl  vAlid  dunnQiins  Pria«&  J  cldi^k  nBg>|i^|r«nsi|lfjn  and  FIflg  K.I9 
valid  Ounnj  mo  Pnaw;  ciotk  injiIivj  irariB-iion  rhMs  triti  mj,  ba 
incugivi  a&  cpcofla  njijnjions  and  may  »  uiaa  Ilji  n^pmcrv  ana 
syaipm  maoflgflriiDfii 

Nan-MaikaUs  IntanLipl  (NUi) 

^  napalivs  [rians'Lion  ari  mp  NMi  inpul  imliiljetthii  inlvrrjpltwLfFncB  A 
ttiQi^-iQ-i-s^  liariaiiion  jniharcq  an  \/\re-rfMpt  t^kmntv  Bhai  Lha  cur  rail 
inBlFUCtlDn  llcC-mD^BIad  Tne^il  rca  khl-mrupl  ^W^XIj  msliucilcn  mi/tA 
epLecuwU  loBnvur-Bihal  lhBinlflriuc»l  *iil  nv  T#f-Dgni3MimmBdiA1A^  The 
P*Ii-Ma»k»blBlrlErrupl  veclfiradaijH^isDafFfJl.B  lErnuLiIiOn  nuKjaJ 
OrOOFPEA.a  (Maliva  mMaj  Since  NM"  is  an  «d^n-innji|iv»  unuui  an 
in1efru<at  v^lll  ^ccur  M  ]h«ra  ii  a  na^i^f  l^an^rign  uhilg  H[y.L;ing  a  pre- 
vious if^  [err  upi  Al»  HQ  inlerrucr  vtll  Dcuur  il  hlMI  rcjna^ns  IQH 

Pluaff  1  Qui  iffH  (auT^;— iv«sc»2 

Thii  m^ffnaa  clotk  aui^ur  tignal  o^avidn  hminfl  rerviiernal  Fead  aiH 
wino  Diwraficfhi  EmKuimjtha  Sop  ISTPI  inWuciwn  nold*  inn  eloci 
in  Lha  I  OH  ilalB 

?hu»Zln  («3  (IN)) 

riiisit|rLEi^9l«^  cinch  inpi^t  la  ItiB  mid^iQprqt^inBijr  inEarnalclQch  ^rn- 
aialpf  i«!iJwaCirniiD#0|iN]o"Wet5EBj  Qvnnulha  liwcHiwar  Jiandbji 
Mode  a?  ilN)  ihBLid  De  reio  m  ime  liign  irat*  to  piai^m  ih*  Esnianli 
dI  miErriiii  iaQi-&Eer& 

Phlu  I  Oul  |«i  (OUTJl— WB5C8M 

ThiBfipfh  vulpul  n^nal  pr^tidai  Um\r,^\of  Biitfiflal  Jnod  ind  wnLa  pp- 
«!ia|iqnt.  Addi«i9BS  ara  »lia(i»Dr  me  ndPraai  Sgnjp  Time  {I>c;||  lai- 
lowitB  !hen«ijjinB  [raimiion  dI  Pnaaa  ?Oui  Eiaculinfl  the  5to^^ST^'^ 
instrud. on  I'^tiJi  PhaH<  i  Oul  In  UK  Migb  ania 

Wri«A  ITM  tt.'W  aijipul  f  >ana1  IB-  In  Im  high  mala,  tna  ncfaprc^uHr  w 
•eaOmg  dBio  Prom  -meraorv  di  l.'O  Whin  in  lie  uw  lUB.  Ilia  OalB  BuK 
cantnina  valiiJ  da^a  ^roin  [honikcrgsrsH»9iiQr  whicn  i3Id  ba  aloradal  !l« 
andr^sseo  maiTiory  l«j|.gn.  Ahan  using  ma  W55CB16,  bib  fl.'S  ii^nai 
may  oa  s&r  [&  rh*  h^gh  imja dante  alain  by  9l4  Erxabie  (6e^ 
Rudy  |RDV> 

Thiib.a.rBfllioriJiigriaFpniJitaliB  Ihal  aWail  lor  lniBirjDr(VM.I)  inBKuc- 
utmnji  D«n  aurulaa  Bilo«inQ  irw^jtai  lu  hailam-ration  of  IM  imcro- 


piutnlzlin-  A  Isi  mBUt  lOa'C  laiBl  full  IhII  [hB  ITrtl ODrOCMlOr  -11  Fll  CUF- 

(«nl  ililt  (nole  Ihal  wben  in  iho  Emulalinn  mode  ma  wascaOE  itBpB 
ony  during  a  raac  cyf «)  a«ivin.np  BBV  lo  Lha  acii>B  high  nuBiiiDaia 
tnt  mLr-raprQCftMOi-  li!i  qpnimue  ^a-i|k3wing  rha  nesi  PhaBj  f  In  Glcck 
iBgaiFrif  rransili^n  TtwPDV  signal  ii  inle^ndlly  puilaaip**  rnriowlng ina 
fluacul.ijf  qia  V^.llEflntBr'upLLW.aii  maliuGlion  anaihnn  iniumad  la 
lltaJimri  ttal*  whan  i  HES  /iHCJBT,  N^i,  oi  IflQ-omarnal  inlarrupl  IB 
pravidM  rriis  r^aiuiB  m^y  bv  used  Ici  e^immaia  "niarrjpi  iBia^^cy 
piaciryilhaWAI  miinjcrional  the  de^in  nine  nl  iha  IflQ  aarvicpng  raui'na 
iri*»B  IhQ  di^hi]^  liaq  hasbKn  aal.  Eha  na^l  innlrjccion  wi'l  haend^ urad 
wndrLip^  IRQ  gtt  jra  Tha  pidcaaaoi  inlliiGi  aiop  ari-ara  WAJ  iruirucEion 
I'  PDYhbb  Bear  loresd  Ic  jhifli.  jt^-i*  TIwSIli}]  [STP|  intiruoian  haa 
na  arroci  nii^  itOf 

rbhi  i^Esi 

rhePaaal  inpul  iBuaaaio  inphalii*  inn  micropriKBaBcr  andiian  pto- 
gramffaocuBon  TnefiesarinpmBjIlarBiinyslaiwmui^Mhai  aumuta 
n-Ctl<n>rir|i:iF4:uilrnay  bsLiHaHim  intinliiral  pullup  davigc  TlwPE^ 
sig.r^al  mual  »  nald  low  Tor  al  Jami-I  imc  cl^k  i;yicia»  illa'  V^p  raaahBL 
pperaEingvcliiya  RaaOy  [ROY)  ntir^a»ir5tl  "h.lenEaisDemsrwId  Ion 
During  Ltllaf^BaelumCiliC-ni-sg  FmnQd  IhalaliDwing  pruf  H4g^^r1ltlallU- 
lll>n  laKis  Efiac-B 

nagimn 

Q         ■  KBO  SH     =  Ql 

□BR    -  m  K.H    -  «j 

pap     -  00  IH    -  ico 

>J    1    M    jj    &   I    ;  cje 

P         ^'    '     ■     1      I     Q     I    «    Tnl  '  =  Mai  Irinalliaa 
STP  and  WAI  oiBULCIiona  are  clearsd 
9li|BalB 


VPS    =  0 


M'Jt.  -  I 
STMC:  D 

Whan_Pfraer  4  brojahi  .high,  an  inEarrup-l  BfiQusna  la  iniTiaE&d 
■  ri.W  ramftiri*  n  Hip  high  B^alG  -duflr^  ITia  BLBbh  addma  cyclpa 

•   lnf-Ht-.n1  ^nchnr  BdarBSS  la  [»FI»FC.D 

BftOiwrnDii  ISO)— WeiCeO^ 

A  j^epaiivB  rr^i-iuiian  on  inja  .n^ul  itJi  iheQvpflQ^  iy\  flag.  b^Q-al  tha- 
Pid«isei  ^inua  lPj  Fleqia.lB< 

SriiE^BTilu  |SVNC|— WBSCJO; 

lite  SYNC  oulDul  13  oroiHIBn  CD  ide"Li1y  1no»  cyclai  duiine  «h,sh1n9 
inicrDpiDtBBior  ra  laicnina  en  opcnaB  Ttva  stnC  iia-nal  -s  nioihi  dunrs 
an  spiLidB  lelEh  cycla.  and  wn«n  C'CmD-inf  a  mll'i  RiimJy  |R[>y],can 
used  Ipr-  singile  initr^iion  eKecuhcni 

Valid  Q'ld  Adoraaa  (VOA)  jnd 

Valkl  ProQum  Addraii  (VU)~WUC>IB 

Tn?s?  nivQ  auiriji  ^'Qi^bi^  'hCican^  lAUa  ni^miiF^  tiddrnEw  fittn  high 
ll-pgic  i;  and  Tii^BE  c«  uS9a  tci  rnv^or-^  oi  JjQ  adtiresB  gual<ficeli4jn- 
VCA  VPA 

0  Q       Lnlernal  dpf^/KWttfi—Aiiatmbtnd  Dala  Sua 

iipailaov.  THFJidargsB  Bus  nwy  ca  inialia 

0  I      yaNd  j!irugr-Bm.B^drBB«— ma^  r>a  ictad  ior  pi^miih 

-ca^;nB  conlrc-i 

1  0      valid  dBI-Baad/aai— maf  tia  Ln^vd  lor  ^alAcathe 

■Gcnlful 

1  I       l!lp<c:uaa  iBicn  -  may  »  uwl  lot  p^c^ram  ^chp 

fiQnIFOI  and  linglc-grBp-conlFOI 

VuDinri 

^DiBinBpoaii.aaiu^pirogiiiigBardVsLiBsvalsmlBgiegfMind  Pin21 
pi  me  Fwa  vn  p.nt  an  thn  Vi^Cltil  ahDuld  be  usad  loi  iraiam  gmund 

Vaclor  Pun  (VP)— WESCJIG 

Tne  VBG'lor  Pul>  ojFpulindica-lavxCJI  a^«f  lorlocBliunrri  bai  ngnddraHed 
Ouiing  an  ^rierrupi  wqt>anca  VP  ib  \ow  during  in^  laii  iwg  -inlorr^pl 
seqbMjnCB  cyclm  dwnng  "nmcFi  eiit^b  the  pi^gofsQi  leLdt  tl>e  inEerrupi 
vaelor  The-VPsignalinay  ha  u**dLo«latl  ardpiramliielnianupKlrom 
tauarai  uurcea  by  moniryir^]  lha  wKlor  addrataaa- 
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TibiB  1.  WBSCBlECMnpatttatHylnuH 


1  W«»U'Hi'M3 

1  S  (SEkIi) 

JU44^  pMQ#  1.  B  Iblll 



AlWBfS  paje-  0 

EadrOlE  <). 

4IWB>-B  □ 

Jl  Dl»  |M  -  11.  IB  BlIS  IM  -  Cl 

9  bitg 

r4.  V  Bra  i  Nagi 

D  ■  D  jdsr  rnKfiL  »r  4rlerru|3l 

h  V  tni]  Z  riBQ^  i/^uo  in 

^qqiin-idl  rhfUl^ 

inlflfri^pt 

HI   U   aptrf  ?  rinrx  inunliB-l 

in  ancirrui  mjide 

O  :  unKciown  jiliBi  rAat 

&  nol  TTioathad  aflsr  incvrrypi 

fl  Timiflg 

A  (IBS.  M  A&U  LSn.RDL. 

B  Jump  IridirKI 

fa  cyr^lH 

•CrqQiung 

«  c^ciBa  (£  ■  1| 

■4  c>cVei 

MO  addiiicHiai  crc 

7  BKH  VHCinr 

OOf  FFE.F  iE  ~  1 1  ^PK  bi[  -  U 
on  9»»  il  ins  *(MI.  neCWlT 
0OFFE6,  7  lE  -  ni -  '  on 

FFPE.F  HRK  b  H  ■  O^ftiiack 

BRft  Bil  '  "0  on  auck 
M  tfli^,  hiMl 

.      lnl«rr]jEi1  IN  iBreak 

PanrKjECLAliacllE  U 
RTI  Pan  not  nulled  it  ■■  W 

PBRBUlfiBi)  (E  01 

Rri  PBP  DUii»d  lE  D] 

ML  ■  Q^Mir.r^a  PF4d.  V^Q-ry  znd 

hgt  jTtiLKI« 

EJifi  Tmm  Dl  inuHlirl  uldrBU 
INirIB  IJ 

ERlnk  rtvS     iial  inilru^Lion 
leiliGit 

11  HOV  Puliefl  Dufinfl  WnlE 

■B^gndlE  '  1|l«  waEJ^S02D"lv 
frttcpanr  nlaps  IE  ^  Of 

ign^irgi^ 

wm  innsrp'iiwmicDHH 

13  UrvuEM  OPCOSIt 

A.vlllpbl4! 

OrB  iBiefVBO  OP  Coos  ipv^iI-<h1 
H  ADM  will      ua^  m  rulvi? 
^^slims  ThB  Wfi5CL1E  perlcr'n; 

Md  Dp«ratian 

LriikrkO-*n  and  ifHiM  ~l-iing 

14  Bank  ^cnresH  Mandlkng 

P3P    QG-  Blirr  lesBi  ot  jinleri-upls 

^  -  t  n.^  '  >□  aunng  i/oaify  ino 

E  -  D.        ■  Q  i^nlf  ifuring 
WniB  tr^ie 

HiW  *  D  Dnlf  during  yftiim  cydv 

p.-W  -  adurmaMc^itv  ■r>d 
■iVniv  i^rclei 

14  PiriT 

«ssceie  1  VP* 

SYNC 

svnc 

17  COP  >r>»auti>sn 

SignflluTn-OO'/F  vHi-d^nnl 
SignjlLirHi  fio-FF  r«»rkBil 

1  

AvailBBii 

Nol  ivsiiliiCili- 
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MIcrDprocei-ior  Addrnibng  Modaa 

Tf\9  i^&§CBi4<  LI  Cepacia  a1  □■reciiy  aai]ivsE<ng  15  MBytag  rriamarr 
modas  aiiollfiwi 

b^Atifir  OGFFCD  nnd  DDFf  FF 

TheSiflcfc  mni  m  miriofv  tLCm  OODKO  ic  (MFFFF  Tttn  iHltc^n 
dreai  dI  SLdtJ:  ana  SekK-RpIiOItv  addnulng  ntaJen  vilL  iimavbDe  wiinin 
thu  rangH 

□Lncl 

ThB  [5»-c^i  fld^rrtafng  m^BtarQ  UdlWuiBd  losl-orH  mffrnQi-i|i  regiaten 
Qir«'^l  V  adc^ra^aiig  mak^ei  n  a\nay±  in  EanU  [>  fi^KimCHI-aOSFFrj 

Ihg  Prag'Brr,  Banifc  r^giit-ti  i4.nat£li«f  Fad  hy  thaPaitiUmi  R'^lvrivvi.png, 
-AD^iiluLt  Ad4fhllj1«  It°ii1irf[il,  ind  ^biolglf  litiJvBij^  InTji'tp^r  rtddUVHiia 
maaiii  Cm  ini!rcinDn'|jng  Ihm  Progrpm  Gounler  lion  f  Ff  F  Th(  cml^ 
inHiruciiDni  rnn  nrr^rr  me  Program  Bani  r«giirBr  ara  RTi  BTL  JUL, 
JSL,  »ncf  JUP  Anviuifl  Lti>ng  Prcgram  can*  miy^Eitb&d  Biic  hyiAaE.!- 
li-iDugi^  coae  iflgm#nli  miy  -noi  ip&n  bjmk  bAuhdAnai 

Addnii  Span 

TriH  Qii^  anorpss&pdGQ  iscQriiguaijHinrougihQui  ine  i&UBfiu  adarma 
spdce  Wsr-;]^  aird^i.  rflcordi,  or  APy  riaea  ^i^urlLjra^mayipiin&l  KB^ib 
isint  DuunaaneB  ^iLh  iai:timpmitiiH4n  'fodfrffhipin^  Trm  Iq-Iiowiib 

■  Dirvrr  Jn-dBAiQ  lndir.flicl  iO  m 

DiTHi irflifacL ia\ 
«  DifBtl  "rdiTBtl  li,aii-g  [tJf 
«  DirKt  iP^lTKTLLang  IndcPtdl  [dl.r 
'*  Ab&oiulfl  B 

*  AlM&luli  B  n 
'  anoluii  a  y 

*  Absoluii  Long  jna?kFra  al  p 

*  PiLBhve  induecl  irH^aisd  id  il.y 

rr>e'loll-a«ririg  acdrnamg  irqdttd«4triDli0ni0raindH.inJD'ii:i(^nal  Uela^lai 

Tf<#rity-rDui.Addi«bAiF^^  hidiJk  ^^'-ijitilq  iQFUHtaiih  i-h^i^escifOZ 
And  WBfiCBlfi  m^crffpr-gcBHijii  T^iB  "inng"  iMffsi'ng  msdm  rna*'  bp 
y-vvij  Chg  ^650802.  hijwertr  ihe  high  &^ffo«  IhtaiJOraaa  fa  not 
■vfl.iiHbi«  irk«  h^jdHBre  tWiBiieid  'jaiciipricn-i  dI  the  ?J  cihlm^ng 
mcUBi  ate  »s  J-owa-^ 

1.  Immtd^al*  Addraaiing — ft 


inivucuan:  |  cpcaaa 


3.  Abfloii^ix?  Long — 0l 

Tn-e  ^LQidr  third  ^r-d  ra^ilPByt-earit^E  micr  jtii'jn  ro-imihe^U 


inilrucuan. 

Gv^tani      L  I  I  I 

C-Ot  lu  ^Q^iTi  Lhfl  HMectivB  iddraH  An  iddiEicnxl  Cfrcla  la  rDquiiail 


l-nilniElun:  o^^cod^ 


AddrBBi 


I 


Dirod  PtgiiEBr 
niBDCEivB  4dargn 


S>  AccumulaitOF — A 

Dp«fairf  iE  I  hp  AccurTuia,icr 

6.  fmpI'lAd — I 

Lmti-lre-d  JOdrnssmg  ubbi  b  s-in^lr  livin  inilruthaa  T<ni  oiniaiKl  a 

imjiiicisiy  dalmBcP      irvB  insirudmri 

7.  DiracE  Indkact  lnd#iad— (d>»y 

Tnii  idsrasa  modB  it  cy^ttn  ruUnma  To  J*  tndirtCT.V  Th»  auood 
'b^|^pl|-hpin,lr^Kl"iJ'ii-9*d*/0l^|hB[>irHtlRflBillBrlDj  T(wlO*ll 
ccnienLs  al  ihti  mBmary  iKflMon  m  ■h^n  iT:cimbiriBd  «i1ti  llH  Dtl* 
&?ni  ra^i^lpr  lij  rpim  j  j4-tii1  bat?  aOtfrM-i  TKpV  IndS"  l^vqJIlJviq- 

aadoo  lo-  sria  emh  iddrBsa  io  lorm  tri°  aferiiivfl  addms 


Ihon 


OCI 


I  DffBBl 


-  Dl?ac^  Indliwet  Long  tndaicd — [dj.y 

■pMilh  rhi5addr?^*mg  mg.jB,  Ihn  ?J--^il  H^'etf  i*  P^'nlnOlSO^ 

rhfl  ^um  al  ino  wcond  c^H  of  irw  iniiruclictn  jnd  ihi'  Oi'kI 

rniMi  RtQicrar 

iMlruEUcHir 


apcod!« 


I  □ii^Rt04l»r 

I 

I         OQ         I  i^iiWifdi^* 

■  I  [  ^-Rigi 

4p*fM  I 


fl,  Dliad  Indaxad  Indftiacl-^l^.v) 

DyiB  d9  Chi  iniifuciic^n  uid«d  ro  m«  ium  ot  ina  Dpwi  N»(]i»ar 
ma  ina  .f:  irnJaA  ^nyraiQ'  ine  r-^auit  t^iriu.ie  cNe  laA-Didtt- 1&  dub 
oriABflHici^t  idarati  Tj^^  D&Ii  H^nk  Ptrgif  rgr  ^^Eamp  Ehi^Nigi^. 
otaet  a  oils,  ai  tri«  errai:iiw«  aMroai 
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□irKi  Reqirac 
I  Dlrun 


QlFHI  d[]l3rBU 

I  Kites 


00 


At  mm. 


HcM-bU  Tun  optrind  ■■  ilvMyi  in  Binh  D 


IniiniEikHi:  Dipccd* 


dirKi  iddrm- 

etiselna  bkhjibu 


11.  DIracI  Indexed  Wllh  V— 

rneaistQJiiJ  brie  oi  Ihe  i«^Bl'ijtliij'**a  idiJpd  inihoMiflftMiwCprici 
Rngjildi  d-^Q  lha  T  maf-b  r^fl-giiiflr  ro  -l<]rm  ihn  lifi-MI  iMflcliMB 


JUBTHL 


I 


CO 


ilirKi  addim 


IS.  AbMljIa  InCFsxad  With  H— 

Tri4  *trtcd  -D'^Ef  i''irii  Un^"     1*^^  initrucrion  «rv  -iqchm  -i>a 
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FtaCDirmendwJ  WGSClBlG  and  WE^C^OS  Auamaiar 

SyniiK  Stindiirdft 

ABMTiblflr  <i\r9cUv%  ira  move  pini  of  itm  JUBinblr  lfli<»puBgB  anurce 
prcKirji^  whiLh  yiuvdiritiiuni  laf^EiiSHJiiUlpr,  [nn  inEludeidrHMIini- 
ti^n  (if  gpll  iri4  «nOtl|r^Bl-l>nLS  Wlth-Pl  B  prc^rjffl  Tn IS  li J  n d I rd  fH-Cl LI ooii 

CoFnrrvtnii 

AnaBKmLJler^hCHjIucJiaridej  iiitawiDuiB  jnyiinffoi  ihi  boum;? urci^rarn 
u  a  CDinmflnL  Thfi-^n:DTniii«na»[J  i^inif  dairiQ  iihb  iilo  IitbiEj^v  QLink 
livi*.  Qi  iA/Uiikviiui  ^iDiip  juihnj  Bemi-i::at<gnor  Hinaale"akatt,B  L:a<mnanl 
PFhw  Bpvqiai  e<^4iii^i9ri  may  De  iJS«J  aiA  mil 

Tttm  54ikjre«  Urbi 

Aftyiinrf  *h.qh  i;4UBVf  Ifie  QBnB'Bl-'^n  al  1 II  nfllB  WHaCHDS 
■nithmv  iiKg^tfige  insLructpan  a-iiauld  b4iJi'ridDd  mtu  Tour  livldi  j.  labs' 

TlHLltHlFliHEl— Trifl  IJD^I  Il^i7»|3rhl'ri  C i^unni  gh^  ipf  iri*  1 1 n «■  AiBb«> 
mki5larflri*ilhariUp.ri4b«.t  th#.*tifli-  nnij  mif  l»  Mowed  tiT  iero  □« 
mora  Aiprui^giVifciitf  i^n^iHc^vm  A,n  MWftmb^Bt  *rat  Mtis  an  uppai  *i*nil 
an  rhtohuafriQirplchniiclBn  rhilcHnbp  in  a  l^bal,  lolixig  atinaE  ufpai 
limii  II  gr4ji4i  iKian  iv  equal  to  «i'  ^riAfAi:l4pa  Ajn  Aii^rnGJar  mdy  limil 
Fue  aiph-ac^tic  cnafbci»'i  upf>«f-£A!U  (hkrHiM:  ii  -de* ireij  ii  i^^er 
caw  cr\afBcre-rittt  anqium,  i^tt^  irig^iiij     [r^tiv^i  ^a-  idQ'rttitii  i:u 

lan^     ihioir  ujr  dipqf  ngi  wnliici;  with  hhfl  tQ^Tg     opfl'find  fnUJa 

f  ru  ^pHiiUA  CDdv  Fipid  rr^  apurjiicKi  rod?  Bhiir  uABiiior  Biriw 
chmarwr  inquprif  a-  |mnemon«c3  frorn  IiDis  3  II  ihill  ilin  Mfl-riar 
rn^n  cQiuTin  ?  n-'  in&  iin«  a'  an^  Hpir«£nfld  iria  iJis^i  .r  &  iah^  cgdcd 

Uiiny  a1  Ihgop^rariQ-n  coQfli-in  TaOi-t  3  ndtrfiOiupdiCAia  inriQiTinAiH,  tititfi 
a/no  01  rnors  nkflcnint  iihngudgc  lABHufiFiani  M<kd  ltib  iirrba  rrifb»nuri.i:. 
rriB  Bsifl-jp^iei  tfso^vti  ttui  airrErnrifd  tusvd     1^4  oipviind 

If  or  AiiHn»ur«r  aiiowB-  la^r-^UB  helterL  in  Uula,  lE  muAl  fltu  tlldlH 
ii^H«r-CD9C  iBilc'B  i-n1ne  innemonic  Whwn  laivgr-uv  lHrrvriiirB<UHdin 
Ihs  mnemoinie  Lhey  ahaW  rrvaiad  bi  vquivniBni  (n  fh«  uppBP-cuB 
CQuTiiBrDan  ThuB.  invmnBrnoni'i^fl  LOA  ida.ihnQLElA  musl  Aivtuf-accg- 
nijivd.  jmJ  arp  tquibilpnc 

In  flOdilian  iq  rhg  Tnnvmifnit'B  tn^wn  <ri  T^q'p  3,  4"  iBfrernDfei  miv  pro- 
■"(tft  Iht  BhlB"ifll*  mnemonics  »hQ*ri  m  Tdble  6 

Tabia  T.  Altffmala  Mnamonln 


Blindvd 

Mh 

see 

BLT 

BCS 

BQE 

CHPM 

CMA 

DEC  A 

DEA 

INC  A 

IHA 

JSL 

jsn 

JUL 

JWP 

TCD 

IAD 

TCB 

jfa 

TDC 

TI3A 

T3C 

1« 

KBA 

SWA 

JSL  iFiDulQtnrqcogjrifvddiaquivdlei^lla  J£f4  wfien  lErtatKdriea  wilFia 
lon^  dDEOlule-  adCreaB  jMl  \n  nquvalant  ^o  JWP  w\m  Idiiq  ndrTm^irkQ 

Th«  OpifBnd  Pl«U—  The  oust  arid  liela  itib/  gjiiI  ne  ua-vvr  irun  una 
spBCp  B^ler  a-LJeralieri  ceUa  iK-ld-  Thf-u  awn  Alar  muiL  Qa-^jpabki  □! 
Bl  I«UE  Imfeiiivl'^u"  BddrBUi  ci.lLU:lHCi0n&  Thia  BB^mDivi  ahguMj 
capable  al  btHCifyiriQ  judrvltn  »  IjiMIb.  iniBgan  cjiBRBnii  jnQ  R>?ia 
tifl';inml  (Hjn^r(nii  Tn^  aflivniDiqr  m-usl  alww  kWiIid**  and  aqjDl'iclion 
m  ihg^pvtr^nQ  fifiid  LBbQ^B  B^all  beiecLjqnizBd  tiy  bhicfacLlnBLih^y  a-larr 
iifp-hab«tic  ci^Bracisra  Dk-htibI  nunkbcmhj'l  ba  raeaflnLcad  ii  camiflin 
inQcnIf  IhedBL^iinAfaigilia  9  l-lvMdiuirijiitansiiiniaihiliCBffHDip 
niJiBd  bf  tHBriJingi  ihi  GonaiflnB  wnn  a  £  cnariclHr,  lon-awfld  fsrc  w 
i>rna> itiQ >aeciiiia-i QigiBB cr  LhiB  1tBi^ad«Nr^Bl digiiB  A  f  tt 
Jaihe<-ciH  tehlcfB-  bfa-  Bllo-ived  in  cha  lual  Fial-d.  ihfrri  ihay  *hjiil  M 
■lleM«d  u  hBi^BdicirTuJ  digiu 


Air  ffirtiianlft.  Jn^Mar  w,hm\  iiVi-r  laimir,  ihflii  piD«id«fll  iBui  Hnougri 
uwcayaft  la  ipofiry  nii  u'b^uh  rrui  u-n  m  rif>r«uni0ii  by  a  Bwani^-Paur 
OiE  HQntdcr  uniignKl  inltg«'  i«pr«en[Hl  in  E**a'Aei^mpkvivi4Tirn(ifBl-ipR 

TidIb  A«rian-B  ina  DWirantg  loiirialfl wniich  ihall  hn  raCDgnijBd  irip 
aa-terntileF  Tne  i^nihoil  dun  lab^i  ch-  k-flija  «tjcri  mg  aBBflrndBr  uri 
recognuaubain^vsk^rLin  tiQO  TriBiymnoi  b-b  B^aDa^or  «dluF  ^ruf fi 
rlia  ■B.namD'iBr  cbh  r44:cBrMf«  as.t}rflaEar  Krifi(Ff  J^ul  leu  rhan  llOOW.iii* 
aymbai  al  la  a  IjddI  ar  Maiua  irij^  aBHB'n'Cl«r  cfli^  ruf-agnifri  a&  a^n^ 
griuiar  Ehin  KFf  FF  Tha  avm-uoi  EaT  iiBifi.bel  wnicn  c^annoi  dbIcm^MI 
I'hp  auHmblBr  b\  iho  iimir  rhc  inicrucncn  ib  aiB^inDled  Urilm  in- 
JiF-uCEBd  oi)-iinA«<i.  an  BurnkDNhi  snail  tsBurrv  Ihai  EXl  lahali  Bf* 
bylai  long  The  'cymtHia  r  ar^  li  are-  9  an.a  ig  DiE  iignad  di«,plBi^m^|» 
cWGuiaFfiHi  Dy  i*v<  audmnur 

H-dIb  I^bL  rhf  cpa^and  doea  -noil  QBlarnnne  hvhBilTar  gr  ruii  imm^dialc- 
-s^JcFiBBalnig  leuda-  ana  ar  Iwq  chii  ia  dBiBrmnacI  by  ira  BalUfiQ 

IJwaiaiuafagia'lBf  ThiiiaitanrwrmjwrrarnBni  lon-airBCEivearslireclivaB. 
1hai  iB^I  lisa  auimblii  Id  ^naralp  nrw  dj  two  byrea  ui  ipata  lor  irniit- 
Ciali  inada  Tjih  duricliVBB  crthvDea  ir^M  alia#  HD'r'iB  Vfltmyi  lc>r  ma 
aceumul-ali^r  and  mden  ragialBva 

T'^n  BiMnibl«r  ii^ali  uu  iita--.  >.  snrt  ^  c^^arjiqiHrt  «if|pt  Ehg  '  trigii^tef 
hh  I'Ti'Tiaaialaadilr'^H  El^  iiwir^  wi^iiiFi^g  grb^m  ■«>litH  B«*eL:l«4lrDm 
ir^ft  itfJlkW  31 1I^B  i>pfl"ind  Any  ;f  l^ijMriQni  in  Lhq  OPflJBnd  mUHi  Ew  QB"- 
l^rmQd  bvl^rp  tPfEV  BQlKM^n  laKBflDlaoa  TBtl>B  ^  dfll'llflB  the  BCtlOfl 
l^kgn  Bii;h  QffvrflrHj  at^QipirkQ  ^^>^9U^Li  Oi  int  apBrelur  Cn  J'fl  ttt- 
drnt  T|-iBi:^unwijrrki,i  ahuwaB'lwaCtvlB  immediBLevAlua  ahovir  lhabvMi 
>n  tnaarMr  ia  M^if  h  rna^  appear  in  iruanuf^  TM^^^irig^rihvgpvnin^j 
Ik  ia\if\  ^if^^irit  wrii±h  ]?biijM3ijigfl«  t*iti^lBli0n»t  B^io^n^tfia 
way        ihf  BiJ4r«^trbgu4d  Lh  ratJvcvd  tg  a  34  vaiUB. 


Tiblt     Bifl*  SalKUcin  Op«ritcHr 


Opafand 

if'ltOtDTlO^ 


Ofht  H  ^a-  Haa  JIE 

D3 


04  03 
04  03 


InflTijr  kJcHiOninpn  opcrBnii  i*hBro  Bniiddrfl>»  or  «aprflV9Jon  rBH(Hli*g  in 

an  addreiE.  ran  rwr^wm  maasiarnbiar  ai-iali  WDgnij:«iriaprflUpirnj.r- 
aci-era <: ,|, and  '-,  wriirn rDrce'iv%«D^#{diwi pa^), i«a&^a [aMakuia] 
CI  lr>rBfi  Gyle  (IqkiQ  aMaauiai  Add^aaiir^^  Ir^c^ia?  whaiQ  Iho  ■^^rnuinQ 
lADi^  1^  nn|1i>rCqflJI^0"Hnn?ilBr  ahull  HlKimi  lhiB.|  TtiQ  fltfdrVBf  1}  ("D 
bjrtH  unl»u  Ehfl  ftiH^nblvr  ii  abl*  Eu  dolBmni  ne  l^wlvpe  aH  addiauing  re- 
quiriiri  Of  coniaid.  m  «ricn  cmsM  trial  adar«B-ng  rrvaMH^ii  »'j.ied  Aft- 
drMiflB  BhBN  H  iru-n^BEad  HiiT^a<jefrrr«r  ii  an  adflfMAin'Q  mrO^iB  ra'cM 
rtfiifih  dud  neE  ^tiiLtirri  tnB  ^niire  naiire  ai  Lhn  ^dcAi^  F^*  ^lampit, 


BiflGornplelflitfaquiujiflrl  irinBaddrnairtQ  mckds  ib  nal  rorfaiQ,  aruaiJ^B 
c'  adJiBBaing  cannai  H-  OfierminBa  rrom  conEaiLE.  Ere  auembiar 
ahall  Biaumelnat  a  i^baDyt^Biiditsacs  m  Br  uiod  II  an  miLrutrifin^rjei 
nal  haiiB  m  ihort  Bdarfliiing  ntiaofl  (ii  in  L^A  hvhicH  diFvci  pag* 

mdaiad  by  V|  aJ^d  a  B^nrEadCrBBB  isuEBd  m  Eha  r>pBraJ^d  inflBBKmnm-r 
sharj  auFD^aiin^ir^  eiiand  ins  Massta  Qy  Diamng  ma  mfni  aigniliuni 
Ofivs  HiEn  lenncAi-n  nrdar  casikCpncrinpadEi'-ps&EainsiBnoin  noaOBQ  fa 
«L|fl  itnmBB>iarB  Jdamamg,  any  ^uprosBion  ■^jtiuaH'On  innii  Eihip  pincd 
biikra-  Ehfl  addnii  a.  HJiciid  ir^uiv  iba  ibddrBH  aviBCEian  tharaciaF  la 
ar|yu?«dGnca  R»t'Cra- Eha  addrnu  B^presaiar 

Th«  ■  |ii"i^^>i^^Hjn  pqjnHj  fbarKttf  BlmilL>b«hi0pDrlBdnanaltwnaliva 
to  Ihfll  -ivBMiLMii  Ijarl 

A  icr^  mfliracc  B.-ddrai-s  iiin^icaiadi-riitiefirwaridliAigorertipairuf  Iiqii 
Of  luTouAding  ma  dirafi  pagd  Jiid^#u  «nHra-  irvdnBdr  adirrfau  \* 
ra^nd  G^  ^quai^bref^keEH  dif«i!i  pAfjaLddteiivj  which  Li^Aiaih  vrpfn- 

tii-l  HiKlr^lin^  fern  int^ic^lO^       trting  lyrrpunflfti  tif  parfl^lliiWS 

a'ha  opara.na-i  Dl «  OlCck  mava  inflirucno-n  am  ipacHhad  ai  achjrucank. 
dBV<nalian  bamh  -itia  aF^xnilB  '□rdvr     ins  abrKi  bylaik  ^hsrjlaa 

C^niqamFtpId—  rhg-cu'nfnQni  Pi«id  may  alal  noaQoner  thancne  apacB 
Arifli  Ihfl  QparaLion  coda  hafd  ar  oparaKHj  liefd  oaparidiiiig  on  mtfrucilan 


4S8     A-^ppf'miix  2 


TablaS,  Addrv^*  Mod*  Forrrwli 


jUdnulna  hhxtt 

ilmmaoiacp 


□iiMt  Pig* 


ChliKl  IndirAd 


IndiFKl 


Hi 

HEXT 

Kd 

Kl 

»^ 
#>■ 

■Id 


ID 

BST 
EMT 

j>a 

^■1 
■I 

a 

<:o 
<^ 


;n[>  opcrinB] 

lai-y 
I  y 

K»iJ-l' 

|0l.V 

l--»J.i' 

[^ll|,¥ 

[CtXTJ., 

liE»CT.J.| 
II, Jl 


M 
lm.K 

lil.1l 

•Elt,> 


DV  ^ 


RililiTtinU 

^fllilivfl  IDng 


Slack  NOdmling 


■0, 

•i.r 
t.i 
':i 

Ill.T 

I  EST., 

■i.t 

■E»r,. 


al 

EXT 

m 


l':exT| 
<a.^l 

|!«Ji> 
|lal.>1 

CIENT.il 

(d.sl.y 

Kaljl.r 
l-iEKTal.)! 

a.d 

a.M 

d.ai 

O.E*T 

a.d 

a.a 

■,1> 

a.EXT 

al.D 

al  ,a 

*t.t\ 

ai.EKT 

EXt.o 

&XI.a 


NDM  Trmuisrnale'  (enciamalion  potnil  u  LiMin  plmol  me  I  luanital  OIF|. 
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Tibia  10,  AMrBuJngi  UoO*  SummHy 


bvliiKtian  TlniH 
1  r>  Mhtwhv  c  i(  l«T 

HmoT  UiltUnsn 
In  Mumbvrfll  ^ragnin 
Svouanea  HiAh 

CMfntl 
■  nil  HunVi 

wucaii 

OnginH 
HU 

Mm 
wWCfH 

1  iTrrMliti 

2  ABHIUW 

z 

2i'r 
S"i 

: 

3 

Ji'i 
3 
4 

am 

jidAik 

f 

T 

S  ■ccumulilap 

: 

? 

1 

fi  1  mplwd 

t 

I 

1 

1 
1 

7  □iFQ^i  Indirccl  lnd«iifld  |dl  y 

yii 

sn !  •] 

8  arecl  Ifidii.qi  Indeieo'Lonfl  |a|,r 

SI  Ml 

: 

E 

9  On«1  lnil».«l  InUiFBCl  |d,.| 

a 

Ql?«l 

a 

ID  □inci.K 
1 1  Direct  V 

4I» 

4 

41 1  >l 

gll'91 
1<I  III 

3 

2 

2  1 

a 

13   AQftDfurA  E-ang.  V 

SI" 

4 

!•    ABMIUtl,  T 

IS  A&lalivf 

IE  noilitiLung 

4>i| 
Z!1« 

(|11i 

J./I 
3"! 

3. 
I 

3 

2 

3 

1'  aOlDlule  IndiTBtl  (JuriVBl 

s 

s 

a 

3 
3 
! 

IB  Dirocl  Incirect 

lis  brfiel  Infli^cl  Lwiq 

gii'l 

20  AbtsluEB  moe-aed  ih^iinl  [jurncl 

S 

3 

21  SldCli 

22  SIBCt  R«IJ1.uA 

13  StllU  RBI'Ii'slndi'iBCI  Indsinl 

3-T 

3  a 
«''i 

71)1  1 

1-3 

H 
! 
1 

Zi.  BlEcKUnvfeK.V.  c<S4UT«.Cwilmi[ian  HuckLmtalM 

f  1 

3 

?  a^^gh  liken  add  i  t/cis  iH  orantn  u  iiiwr 

1  M  :  Oor  )  -  a  '6  tn!  ippsralion  sida  i-ei«ie,  aao  i  arivigi  .nunMifiiE 

1  Ghrect  lA^iftiM  Ig^*  (OLJjioE  aqiul  »rfi-,  ana  1  c^cl? 

i-  Jlwa-MiSij.ry-Win.MdJtvtwi  lorM  -  I  Maaicyameru  ■  o 
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CiwbU  and  Appllcjllor  InlormaliDn 

Wnpn  in  Ihi  ihJjiMijfl  mod*,  ir>ft  5EBLk  mny  lus  'nflrn^r-y  iiJ&piEign^  CKK>CH>0 
ra  Od^PFFF  Tns  sfratnuv  juJijiBa^  □■  Sulk  SUc^  HelAEiv?.  iF^j  ^Lick 
Hfflalivp  inDirotl  liil5*Ba  addiauintj  mijana  hiI^  BlAjya-  be  wilmi  1t»ia 
mnffo  In  II1H  Emulai-tin  modfl.  Jhe  Slack  HaJd-m-  range  i^.  DODlDa  l-o 
[UOirr  Thn  Pail(3ivi«^B  □pLuneaandsdiJ'Bbbi'kq  mudn  Ml  irk^r^nmni  dt 
dnoBntonl  DRVDnd  iriiii  run^i  itncn  iCCBUiiQ  tw  or  ihm 

JSl.  J3R<ji  1^  PEA.  Pi.1-  PES,  PND.  PLO.  HTL.  d.i-  Ifl.iiJ  r 

Thtf  Dirfitl  A(jd'e^9ingnioLJ«flFva<ftvr  VBC^B  v^i:*^^  rfiwnofj  regiila*! 
jind  porncora.  tlia  allectlv?  addrga-i  g«rwri1v4  by  Dirm:!:,  Ehrfl±C,>  Af.a 
CirotlV  nijdi«sing  n^a^a  wll  ilHifS  b«  ir  Malivir  miTijE  rArig« 
QQQQOO  OOF'^Ft  Wfinn  m  rM»  Eri«uifll4d-n  -maae  ln#  fiir«cl  anr^rming 
finflE  fllXHXK30lol»W^t.T'tffCirp*|DiiSc[|flriEl[D.rflCl|,T  janrsisirg 
medfla  and  Ihe  PE"  inalruLtion  wh^th  wi*!  incrBm^t  iiflrfn  OOOOl^E  or 
UOOFF  inio  ine  SuLk  area 

^^hen  -n  Ills  EmiDlfliLan  mods  *iri  DH  i«  npb  HqUiil  In  jriii  D-retl 
ad^re&Eing  m.g4|fi  and  itnt  P-EI  irdirucli leUv-Ln  ffW  incriFnini  Unm 

V^tbffn  m  Ihn  ^m-iilaricin  mudt  ind  DL  1'^  nor  aquai  [a  Hni,  m*  OiTKl 
aaor&55inn  ranga  19  DQDOOCiin  MPrKP 

Abfalulfl  Indflji-Ki  Addriuing  (W«5CBl6  Onlrl 

9HJa  111?  diTQi^r  AddiD^^ing  mngc  ir^t  W^^CD^ann  f^&^AOf  lOdrmLtn^ 
ringi  li  0000  la  FFFF  indanng  ligm  pigo  ff*.^  ni&if  ■e&ull  in  a  OCT' 
djil  PtKtPi  *hen  uMng  lire- WGSCO^m  Jn  conwag?  inQB«int» 

ruhjrv  MkrepfoctHOff  wgscau} 

ing  rriG-jH  Pur  borh  ini1«r  AiiiZ  on^^t  aaomu  ^nflFjilinn 


jiBO^P  should      held  lo*.^  Ici  jjniipd ji&l  iif*tji4f^.td  g^?  c^rle  Al^ti 
ABOflT  itr*lfl       ajringlrve  ADorfl  Inlirrupi  wquoni^A  I'lP  AHoM  Inier- 
f-Lipi  will  IK-  afi^rwd  ir  li  f\at  fAoamm&nafrf]  m  iboT  rng  Atio^  inior-iupi 
Thp  AflOP'T  mEomai  lal iLh_ii_clB*r*d  lJuiiftg  ine  !5CQn(l  cyciB  ol  lh»  ABon 
iryltirutH  '^sie'l-no  fhfl  '■eORT  .npul  aliflr  IfiO  raiiomnBi  imilrjcci&n 

nyclu  MijL  cju^e  ragnisfi  la  ba  mcdilifid   

4  nM.uo^Pr-Wfiii:Dr.QCfi»ar  iiatuE  rr^rKfiiiflC  ir  abort  iiusAtaii 

at*  r  a  -npqlirv  ^ytl»   

•  RTh  Procmgr  iUUt  wi-\i  Ctt  mo^i«iM  il  ABOflT  IB  UBBFtBd  it^r 

cycle  ^     

■  IRQ,IUMI,  AttCftT  SRK.  CQP:  WM^n  ABORT  ila^DMCAd  arctr  iLycle  2. 

PBP  aisd  natJ  1*111  bdfitm^co  lEFnulfldcr  moO^f  ai  FBR  will  bHrama 

Th#  Ab^ri  lAlarr^-pl  .naB  BBan  flflsinrigfl  lor  miml  mBmn>r/  ay&lttm^  Far 
la  ItiB  abGVB  condiiicni 

VQA  and  VPA  Vtlld  Mamory  AddfMi  Ouipui  Sl-ginali  {W«&Ct14 

VlJA  ?r  VPA  arv  Ni^h  arid  JLJiiii^  all  tblllflpGrCl^  l^ft  Addrou  Qu» 
i«alwdf3-ai<d  VGA  i-nd  V^A  uiDuid  Oa  uwi  Id  quality  all  rnamDrv  GyD.lra 
inar  Mnan  and  VPa  cfa  norh  lew.  mvnhd  adnarfism  may  D? 
gc-hQr«icd  frkt  P'ligs.ana  aaniK aitdFe£B«-cf]uia aisn EMMi-ivjild  Tm^Miii 
Lnduvl?  iQ*  EK^nMdiEii^ri  ori^  trie  frCnis  v«riien  only  irw  b^a  jicldilmri 
occurb  laan  upEiunjiicyEJelmr  iA9[ru£riani  v^n  cn  aa  rnamcKy  ^rvflniTiv 
ma^x  negiuavconiitii^iaciiiv  TrkiKi>prianar  cycle  □eco'nm  j  Bidrmar<j 
fyriA  rat  itM  ^Bitre  ■riACrnction  all  iniiuLCMcini  utii^g  ine  i6-ni[  vnaat 
^^\UBtff^oa^  £nfTiin#FLE4d-Wnfiiiy-Wriiaintii^ciiCn#hBriL^iriaB- w 

ApfM  II.  IM,  lie  mna  11*  Cs-liic  S-^aiama  ^Wfi!tCB1BOn[iF} 

VQA  and  V  PA  D-u I o Q 1  DP  uWlloqua  i V  il  no  rajHj  flurinQ  diiliap€iH- 
Imnen  Ajj^ii iT^i^nUb  Q^nf uJe r«u' Apfilercj^r flu nil li miliar hirdwrnw 
aoflwirv  bunfiguFMii^ 


DB^6A  0p«r4lkciii  «hmn  RDV  4  Pullad  Low  {WBSCfilfi  DnJr) 

!AhAn  ROY  It  law  CJnra  B.jg  is  heia  1^  ine  Oiia  irjinsleT  buib  ji  e  ffZ 
nigikj  ina  G«nk  maatns  enrarnai  naraparei^i  la^c^  ericuid  aa  laicKted 
ifchth  The  tfiP  fJnck  or  Fl[>"f  i»  ld"* 

m;k  OuI^i  Only) 

jn^  u  I:  Duipu-i  'i^iinrE^  irve  vaIu^  nr  ihe  M  ind  K  qjeb  ai  p^ocviur 
^ijiut  'ite^iElflr  Tnei  REP  SEP  ind  Pi_P  iniVueilKirkE  fliay  cianan  ihe 
yratpijr ph>i M  ^na  Jibiis  iNcia maciP^ M:'X  otJipuc  lair^aiiddur-ngiHcH 
■nsLrijcliijn  t,cln  ldllQ.-rtinfl  REP.  SEP  and  r*LP  narrutli&n  e^eculion 
'•^ii  i-.fc\Q  \-w  uBfict      liLc  oeciMe  If  l^r  cvcifl-  cri  inr  no"^  inairuLiion 

AN  OpciHMi  Funtlkon  in  AH  Modaa  of  Opn-aliun 

II  ^hgi^id  be  niir^d  rnai  an  opcedn  Ivnciron.  <n  all  fiode^  cr  oaeraNQn 
H-Dwo-p^',  >i?nic  iriakutlidns  snS  AdrjrBMing  jnadM  bra  inien^d  Pg- 
^E!iCfii6^4-e>iriddmiiri4  ana  are  iriBrBfofeieEMj-Hfui  ronhB^^ESCQOZ 
Thfi  T'DHi^hin^  iB  I  11  E(  inii[rutriani  ei^a  aaumEing  mgQgi  Ahi^n  die 
pFin^jir'l),'  mlf'^daa  iat  ^mCE'^t  mo 

JSLRTL  191.  Id  I. y  JMP  ftl.  JP^L  ai,  ai  a 
TliP9  i^ll-uwng  infiru^Fidiii  ffiAf  H-         iviin  thfl  kV&^CBLJ?  Biitn  thau^n 
afiink  Address  inol  rnijihiwe^-efl  DiMf^Oala  Bu-s 
PHK.t^B.  PLB 

Tha  rijilOHing  inaLrLji:liD-»i  haw  "limiiBij  i^e  m  tht  e.muifltiiKi  mods- 
r  rhp        antcStiP  inslrutEinna-tflnn*!  r^Ddily  IhB  M  ind  t  fitswhBnin 

I  ha  ErriMidlfDi  ruDcie  hn  l^ll&■^adaE^le  W  ind  X  bit5-Arlid^h<fayi  M-dign 

Clog  IE  1 1 

■  UVih-n  in  iht  Emu^aLiDr  i^Qdc-  ll^e  V^PMnd  UVN  ir-alrucrion-t  uvh  rha- 
jtarifl  V  lni*E'^Hefli-5lB'-s1or»tifl  <w^t<T^^rf  ma^T^ti  meMUPa^^d 
MVN  ■nsiii^[;l:iLpns  ton  Dnl^*  nuwe  daEa  iiMlPiin  Ih^  rntuik0.r/  rarigfOlt^ 
C^Durce  BanKlra  CKIFF  iQeilmatian  Bark)  ■L>rlha  ifWCftl^,  V^^dDOOO 
Ea  DDFf  -iQr  Ihe  V^SbCeO? 

Ipidiraci  Jumpi 

f  ne  JMP  lai  aid  J*^l  IH]  inaCnuclicns  uh  liia  di'sti  B*"!*  "i^r  inoi^wi 
jHiarf umg  #n9ie  JMP  la il  MnLjiJ^H -la  11  uae  1h«  frosnir  Ban^ Igi >n- 
direCL  j^drvsa  EaljEn 

SwIlchSng  Mod«t 

Wrk^n  ^Aliening  IrEvm  1l%^^dJ1fwe[^l>de  la  th«  Emu-lalipn  >nt>dv.  lUKdnfl 
M  mil  or  ipie-  Siaiu-a  RBBuiar  aro  tti  higr^  ilogx  13- 1^  p^iflh  by^o  fl'  l'^ 
StaciH  11  Ml  10  ai  andthflhiB''  Dylw  eriti.  K  i/^d  v  I*ii3fl<  .FSpg-iii^  irr 
Bfll  10  W  Ta  3Ava  pra^icua  voluos,  |h*sff  (r/lm  ""w*!  alwJf*  9lorea 
BePDJPcnanging  mi^JB  No^B  Ihanr^lowDTteol  IheS,  H  mnj  V-RrgrtE&ri 
aridihE  law  aicr  mgriQ^EioHhB  Accun-iLfJaEur  1  Ad^d  91  -aic  n^l  nHndda 
Fiy  i  maat  cnanga 

Hon  Hardware  Intiirupli,  B^K.  tnd  COP  Ifit^iiictlona  Airocl 
Ihfl  PrugrBin  Baniijnd  the  Dila  Sink  Fl4gitMfl 

^h(?ri  II  m*!  Ndiive  mciCc.  nc  Pugrjm  Bj-'N  leyialfr'  i^BRi  is  cispi-iidTS 
OQ  *hfln  a  narflv^a'e  miB-rrupi.  ^Bh  01  Qi^P  \t  *?*cuflect  In  Hie  NbEive 
maOi,  prpm-aua  PBF1  ct^nlanls,  -i  auta™i-cmiij  iJ-nd  an  Slick 
inEnHEiMulation  nnode.Ehfl  PBR  pnd  OHH  fSfliilwiAreciflflrwiloODwhrn 
a  naiCMiB  nlar^upl.  SflKor  COP  is  BWCuPSd  in  EhES<fl±fl,  prevloiJKEDfv 
isnii  idP  ma  F&R  Bia  iii:^L  aulcn^aLicaMy  savad 

AJvtvihfli  nflfituifi  E*oinlnla*rupi  (atTl)  ihoufd  <lwJYlocell'WUlEE^^rB■^ 
1h«  »rnie  'motif  AiFiiCl^  i:.nQinBJly  ge-neralad  Iha  l^^o^nJpi 

Bknary  Hoda 

Tnp  ^inBiy  siriodft  li  «ei  fhnenafvr  ■  h-»rd*difi  Or  floilfca^e-  iMarrucil  is 
«"Kul9d  TPiv  P  iiBg  Viiniin  iri«  Sram^  R-tgisrcr  n  ci^hH  1:1:1  'B'ci 

WAI  ImlruttldO 

ThaWAI  ii>SErucBion£ijlliPDV  la^«  CnaprocHScr  in  rnB  WAI 

-(^i*pp«bV  moil*  wKPfffTTor  RESET  Win  liimmaaihgWAifcndiuor* 
antf  trill Ipr-Eonu 01  EuFha  inli'rupC'nanOiHr  ranl-ni  Nalerriai  an  ftSoRT 
if^pkiL  will  aburi  lni  WAI  »n4Lm<!iii^'i,  aiir.  will  finl  Fucan  prQi^HMiiH. 
WiBii  tha-  SLaLua  flegi-slir  I  i^s  d*sflDlfliai.  tre  iT^O  i.nEBiTijpt 

i*iil  tiL^iv  Eha  neiil  ^nsLrutliDn  iTDila^mg  w»6  WAI  ^riMTuCHOn-^  la  tn 
SK.SLU\t<i>  yilP'iB'Ji  gifinfl  ro  in«  TSo  inlHJrupi  hinij4»r  Tr^n  rf-eirii>^  m- 
aulla  in  'I'lB  h\^imt  bppvJ  rrtipflnwlfl  inTflC  inpur  WhuA  an.  inrer«upr 


lSFBMl^;.aJ(^sfar■^BSlT^-h,cnectLJ■5flun^g1^&WM.^■,|,utMn 
BJtKOHQr  w.li  im^in  10  irw       -risirutntm  OLh*J  rhfr.  FiE5  (hiahrsl 
P'lonni,  fiBDpr  IS  ini  n«i  h.gnsii  piior>tr  rai^rmo  u,  Swi  n.  Ibq 

STP  Inlruellan 

Th.STP.n5Cr^i:rir>nd.;aBlB.rh.o#ai;lKiimalJc.reL.ilr,  When Llii.ljrBd 
lr.»?tiQe>.,iniia.n  ins  Ugh  stale  Inimiicas*  in.OilaBua  t.,\\,tni.n 
■r.  (hoojia  rrinslfl'  5i«i»<r.d  the  Binh  aad.BiiaJi  luil  E«  r,.uHiWs,eU 
BnlothaDilaej?  Mpone.eLui,ng!n8Stf-n.ttitf;i.ni.,Lh.BESsi,nilis 
[m-D-H¥.rpul.si'icncanre!1srnn,iKaEeiiffr  Tt^ajirsfnHr ixeiiiriDa 
tit  onjoimflir^pSciDC.,  -nichoctun  OMfw  lallrnff  ,daB  or  irw  PES. 
ifiBui  f^Diel^LrnBe.ls.h.loM-rialof  ™urt»slaw,.<ntio|w-si,ngnran- 
tjoluie  nES  ooai  ^lgh 

COP  Slunilurai 

SiBimures  ■JS-Tf  mj,  tis  iJi.r  diJied  Ahni  EngniturCT  BC-FF  no  r»- 
WOMCpcods  Uu 

T>|?  l^iDM  jpcfldo  rtiil  B=  u^fiJ  on  lululm  miciojirQcouDil  For  a.JmDie 
">»  new  WSSCai^  ui04  ihij  odcoob  la  ccobhh  as- nil  Noii.iig.BD.rii  ar^a 
tflhsf  M-Bi!  mainihaitsis  op»r»i.i;TiB  Noiiihit ine  W55f;B32  will  ceo 
Ifug-ID-Hlup  raplarpnwnl  IQi  IP.  M§sCa!G.  ano  lan  o6ui,d  «nete  111=1, 
ipei>O.M-li.[m«rh ^'ocauing.k r?»j,.ed  The  w&EcajJ »ill beiHiuijIe 
m  rha  nifli fuiurp 

RDV  PuIIb«  During  Wrll* 

TneNP.10ShTO?5iwur(Msi(Kpau.injai*iiHopwairon  inco^asl  Mln 
"^S^^Sr*  m  slap  durvnq  »ril«  o»rat,nr,  Th, 
Ivfti'.Haz  slnpt  During  a -BriieHneiri  i-iJij  NjIito  mode  tiui  d«ii  rul 
t\Qa  *he*i  m  ihfl  E.nbuiA.|uDn  mode 


WDC  Topibpa  &|ii1»iii-Eirul«lar 
FMtur** 

•  RMi-Tweemuiaiicn  arm*  WMCMS/Blflarn  iiw  uv^scoz 

•  l»Biari™ip«rtj,w  AuBio  IIh  Computer  as  HiffiKMlLBiri  imdviiihiJ 
»  18K  bylBi  or  Ennuifttinn         [Ti»|iMrii(i  in  :k  btoeki 

-  OBlioraiF«MBipin!ior1is?5«H 

■  OCMoral  handttine  R«l-TiJTie  Tjics  Bmia 

■  Cofio^ilBOS'Slft  Eniuimor  PM  u<iii 

•  Singla-Sleo 

•  ^BblllrxtmimorvorupioZMamBcniret^idlM 

■  Tl'tiiC-liUlirMliBmnlearnal  legiitarf  pi^rmrg. 
—E^a^  unAdareM 

^B'sahian  ttaia 
-BfsaiiijnConlrol 
-aiaiii  oniJa*iEn(u> 
— aroiii  on  Nlh  Otturanci 

A  VlCrdfldCCni^eiBfHjEIDn  [irri»4- 

»  AHoaid.Ubl.  in  ln-C.icuil-E™Nati(j-.cnirK>riv.ip™iBBico<>[,Bijr«iion 
PfOdkKI  Oinnilf  IV 

rnt  TOOIBOI  Svll«m..tmuai|cf  conwis  0(  i  U>in  Unil  mn^  lnre^BCBC«ra 

inu  p'ligs  ipHifi  ong  or  the  i.ao\e  ComouHr  i  «<pif«ien  iids  xha  Ui.n 
Un-i  pr^-amn  rwceiur/  Icflic  lar  BmikpcintiUB.  ji^jie-iiBBping  ano 
minEhfig  In  Ih.!  cunrigjiBIiDn  IflO  u»r  ms^  piiromi  DuiL  cjBibuooH«»- 
tionsorLiii  ir»l(,oitio>  in  Ihe  Euil  jalion  Men), 
Wiir,  TUB  Dpi.g..Bi  Bmi-Tirai  r.Bce  awo,  ttie  umf  nt™  nu  <»  nn  at 
ITH*  mtn,g,f  ^iihn  ,  *i„nc„  4,  ^145.  micnitw  tvtim  A  npnonai 
brnu.i«i.«.  HAM  E^eaniictn  aaa.di  h,  ,,.11.^10  wn.cp  ,ne<aaa«i  rha 
L«er^„,„^J4,1M^  P&M  DjrSis  hywj  ni  Z5t<  t,yi«.  with  mampr^  car,l^u,. 
Blic*^  u"MJi«  sorivraie  conWTji 

TheloolDoi  maj,  ba  luM  wiihw  wHhoul  (heojjmwiai  Pc*3  Unii  WHt>  ilw 
PtW  Jnii.  ine  uMr pi^  imrs  ih.  p-mcHype  -iH^fQcrKmo-  itKh.!  for 
HfdwB  SBBug  Sintft  rh,  Mbii  Umr  rimain!  i>w  uFna  'Hi.cMvH  a( 
rhamitreprocpiior  Iha  uaw  gtm  ncM  hjva  it;  jbbc  1  ni-  se)  of 
Toollioi!  cominaiiOl  tareacMypi  oroceiBar 
ApplBiliB  u  a  iriKlinuik  crTAppla  Campuiar.  inc 


MVH  ana  MWP  AITkIb  an  Ih*  Oatm  BanK  Hflglalar 

rniMVN  anj  WVff  .nstrMLIiona  cnanga  11.5  [Jjia  Bmk  Reg, alar  10  In. 
fJiuB  nl  lit  iScond  hrte  of  iho  rnslruclmn  laBslhriaHcin  tMnk  a9dnsg| 

Inlam^i  PxlorlllM 

TriB  rrHlowing  ,nle.(r„Bl  onoimoi  witl  bP  in  eFF*cl  B.lll>ijHi  moJB  ItlHB  1MB 
irteriupl  KFur  ibi  lh«  Hmg  [img 

Higl>eH(  PliCr*!^ 

NMl 

TFinaNri  Irani  l-fll)  is  IS-BJl,  or  ie-BH  lo  e-bll  RaoNlWl 

WllianilBrslrom  anc rigiatei iuanoin*iriml iraLilm a riill  tg.tjit ojioli 
IrotnihsMnicernBHIflr  Tna  fl*»rina[ion  regijiBriiiew.ll  ijois.mine  ins 
fu-nuei  or  Bira  acruaily  stn.^tj  m  1lw  diiiirHHion  le^n,,,  Inc.  vnuei 
isiorBair>mBproGC!saisnigj  naaiBlB  Tns1oHQ*ing  ireai-iv,  IS-M 
Iransrari  raaa'dlcsi  u(  ilio  sLcumu-latur  sue- 

TCS.  TSC,  rcO:  TDC 

SlBch  TVanilan 

rtJi.n  inttii  EiiLljiiiorimoM.^oi  IS  iDitan  inin  En  In  tBii  caw  IMB 
■ctMrnuiaw  mllnotlitli,ad"(JinlB3HLjminBa1c;5miirucrior  tfJhe" 
.nlheNiinwniDOie  inee  ftccumulsli^r  1,  irj.iiileiro91o  Sh  rjon  ihat  m 
MUilftfi&nuial.iwiaorl  Naiive  mean  |he  lull  IE  biu  nl  rnesinirli  ReQ.i- 
lsr*B  irannieirao  in  ino  1,  b  a^aG  ^cLjmuHion  woardi,,,  or  in- 
ol  (he  u  bit  m  iru  Sialid  Hvg.iiBr. 


Addltl«ri4l  InlormMInn 

For  ujdilianil  irti».mjiion  or  ih«  W65CW2'BiB,  lalar  10  ina  iQIIomno 
BLBIitJI.oni 

PiOB'imftilnB  ilii«fiH]g 
^Hliam  Laesiali 

SybE*  inc 
2344  Glum  ^1 
SailidlB','.  }47tD 

Tn»a9a2,  tscai  ami  ttoie  H»rKlb4ah 

5-lr»B  Hienoriii 
fJ^bsr  ^yq-iginB-.  Jnc 

B*3J  MBv^.Bld  Rd 

CHii*re.ia"D.  Dh  *MK 

MiLhanl  Figner 
Os&urnB  Mct^rm-  Mini 
IBM  Tanin  Si 

helev.  CA  947ID 

Progummlrtp  ^  BMIt  Jnciurilng  irttflXJ.  BSCD!,  and  ASMl 

□*via  Eyei  ana  flD"  LiLflE*  ■■™« 

Prwiiica  IHaN  Prna 

A  Di"iai<n  al  Sirnon  A  St"uaHir,  Inc 

{iu4r  &  H«l,tHi^  iBia^ 

ClniGuHA  Wg-ilarn  Plan 

NaviYorl,  NY  ICMJ 
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P<ch  aging  Inlormallor 


nanic  LtiMA  Chip  CiirMi 


1.  Poi^fl' iui3p>ypini  noE  miiLnfilqcn  ihe^D-ipin  veniDr>  Theu 
fiamai  auD-pIr  have  benin  td^arj  Far  imp^avoid  hiahi 
pyarrcrmifve 
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Ordinn^  Infomatlon 


WC— Custom 


PL  I  -2 


f'^PinLi  e-LeMi«j  ChinC«irio7 
Q— Onjip        PL-Plailid  ChipClmer 

M — Si'C  [B  'i^s-c 

DeaiQRjlDis  ^rlerlpn  lot  Ifie^J  jnd  patw 

SI«nl_J  Ufm 
-1  4MHj 
-6   G  MHi 


Tit nn, til  or        uirKirKeiur  t>«  'wilmim  <roir 
Trw  Wntprn  DBiign  Canr*r.  Int 
Zie^Eaii  gia«rvFiDia 
Una.  Ari^eni  as^D^ 


WARMING 

MOE  CIBCLIIIS  AHE  SUiJECI  TO  OawADE  FBDH  SIATIC  QISCMARaE 


K"  Mil  ihmagtf  ir-.ip  la  , 


iLdlaridl 

1  Ufilll- pj.i,  oni^  II  iimdiBi.  >>la|.ifni 
3   G(0..ni.(l  ji„mjf,  ,,ai„j.,„^j 


■  ijijal'L  Nijhm 


InimiTLii^  CDnlMJln:  Parnn  i.  pfs,wij  yrUulKnillv  ind  wnojl 


R*pH>««nl*d  in  youi  una  fay 


n«|p  CfVt  Irv  IIH 

Tha  Wflgtern  DaMgn  Canter,  Ine 

IW«dBl^^  OWL 


J166E  arowri.Hd/MeM,AZ8530a 


APPENDIX  3 


The  Apple  llGs 
Tool  Sets 


Approxiinatply  half  of  thi-  Applt-  lies  tool  sets  lire  located  in  POM.  (Thpy  are  ma,rkfd 
with  a_strrisks  in  iW  ttihlc  liflfnv.)  When  PmDOS  Ifi  starts  up.  it  instiills  \\AM- 
bascd  biiji  fixes  aud  [■nhanLi-mtiLiti  lo  the  BOM-liased  tixil  sets  hy  c'si'ciiliii^  the 
TOOL  SETUP  program  in  the  SYSTEM/SYSTEM. SETUP/  siibihri-ctury  »1  the  IxiDt 
v'oliinir. 

RAM-l)is.ed  tool  sets  are  stored  on  disk  in  files  with  names  of  the  form  TOOLxxx 
(where  xxs  represents  the  three-digit  tool  ^vt  ruimlier  in  decimal  form)  iri  the 
SVSTEM/TOOLS/  siiibdirectim  nf  the  boot  v<:hinn\  Yon  can  iii>;tall  thesf  tool  .sets 
Frcjin  inside  an  apptiL^lion  with  the  Tool  1/Kiito/s  LimcITikJn  and  LoiidOiieTool 
functions  [iet-  chapter  3}. 

The  macro  files  referred  to  in  the  fitllowing  table  <:i}ntain  llie  iiiaero  dcRiiitions 
for  tool  Sft  funttiuiis  In  assembly  languagr  form.  These  files  are  included  with  tllc 
Apple  lies  Programmer's  Workshop  (APW). 


Table  of  Apple  IIkr  Tool  Sets 


Tool  Set 
Number 

Toot  Set  iVflmft 

APW  Macro  File 

001 

*Too]  Locator 

M 16.  LOCATOR 

002 

*Mejnnrv  Manajjer 

M16.MEM()RY 

00,3 

*MiscellaTietms  Tool  Set 

M16.  MISCTOOL 

0Q4 

*yijiekDraw  11 

Mlfi  yuiCKDRAW 

005 

"^Desk  Manager 

006 

•Event  Manager 

M 16.  EVENT 

007 

"Seheduler 

M16.SCHEDULER 

495 


Tool  Set 
S'ujnbfr 

Toot  Set  Name 

AFW  Macro  File 

008 

'  ^fii  1  run   \if  3 11  £1  Kft-*  r 

009 

JJCSK  1  up  DU!>  lUUl  uGl 

.\1  ID.  AUtJ 

010 

■1-   -I  UOL  IJL  t    1-          111    _  1  (J  II        1  Ll_3    <i3/\l  ■!  ^1  1 

MIR  ^ A WF 

on 

012 

Mlb.  1  h.A  1  I  (JUL 

013 

[interna]  uscl 

014 

JVl  ]  D.  VV  i  IN  Ln.1  W 

015 

\A  f    1 1   rL^  U  n -LI  1  IT  ri^  H 
ivllTlllJ  l>ldJld}^(.r 

Kilt:  Il^cmtt 

M  Ib.LOlV  1  Htilj 

017 

■J  y  AL^UI    1-illa.vAC  1 

JVlltJ.  LUAUtn 

018 

fTli  iif  H^lriiv'  Aiiviliapi.'  TV^nl 

1^  U  JV>I^  J-/  1  ti  t>    T\  LI  A  J  i|  1  p4  y       L  vUl    u  1.  L 

IVllo.yUAL.'A 

019 

Ppifll     nA  1  Tl  □  O'Jj-T' 

i  1  1 1 1 1  ivluilriEC-l 

jW.  id.  rrUJM  i 

020 

LineEdit 

M1&.  LINEEDIT 

021 

Dialog  Manager 

M 16.  DIALOG 

022 

Scrap  Manager 

M 16.  SCRAP 

023 

S[and;ird  File  Operations  Tool  Set 

M16.STDF1LE 

024 

Disk  Utilities 

[none] 

025 

Note  Synthesizer 

M16.NOTESYN 

026 

Note  Seijuencer 

[none] 

027 

Font  Manager 

Ml  6.  FONT 

028 

List  Manager 

M 16  LIST 

*  =  tool  set  in  ROM 
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APPENDIX  4 


Number- 
Conversion 
Functions 


Tlif  (ntt^ger  Muth  Tool  Set  itool  set  11)  inchides  nine  functions  you  can  use  to 
convert  niimcric  data  from  one  numbering  system  to  anotl^er  fSee  the  table  below,  I 
Tlif  three  riimlicTiii^  systf  ms  supported  :irc  hinirv',  decimal,  and  hejtadeciniiil.  The 
purjjitht  of  thii  ^ipciidix  iis  tn  L'\.pl<iiii  how  to  ujii;  these  cuiivcrsion  functions  in  your 


Table  (irintfiier  \T;ith  Tiit>l  Set  Niinihf r-'C\)nversit>n  Functions 


Function 

Des-cripiion 

lnt2Hex 

Cunverts  tLn:*igned  integer  to  hex  ASCII  itring 

Long2Hex 

Converts  unsigned  long  integer  to  hex  ASCII  siring 

HexU 

Converts  unsiisned  integer  to  hex  ASCII  string  on  stack 

llex21nt 

CoQverts  heX  ASCII  string  to  unsigned  integer 

HexSLonp 

Converts  hex  ASCII  string  to  utisiRiied  lon^  integer 

liit2Dee 

Comertii  signed/un^iii^n'^fd  integer  to  decimal  ASCII  iilring 

Converts  siRned/umij^ned  long  integer  to  deeinial  ASCil  itrinp 

Dtc2iiit 

Converts  signed/unsigned  decimal  ASCII  string  to  integer 

Det-^Long 

Converts  signed/ unsigned  decimal  ASCII  string  to  Jong  integer 
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BINARY  TO  HEXADECIMAL 

There  arc  thrcr  hiiittkins  f<ir  cniiverting  unsigned  hinar>  iiuinhrrs  to  hexadecimal 
form:  Int^Hcx.  Loiis2H<  x,  and  Hexlt. 

lrit2Hex  converts  a  I6-hit  unsigntd  hiiiiin-  intf5i:?r  to  an  A&ICII  string  representing 
its  laluf  in  HexadeoiTiKil  f'ovm.  Here  is  how  tc}  use  it: 

Pu  shUlor  d  TheNumber  ;N  Limber    tc  convert 

PufihPlr  HeicString  -.Push  poinler  to  hex  string 

PushWord  #4  ;Length  of   hex  Btring 

RT5 

HexString  DS         4  ;{5tandard  ASCJi;   bit   7  =  0) 

The  hcxadctiinal  slrinj;  retitrntd  hv  lnl2Hc.x  is  rij-ht-justififd  and  padded  on  the 
left  with  ASCII  (1  ih^iratlf-rs-  In  most  situations,  will  rf>irr\t'  lour  bytes  liir  the 
string  hrcaiise  tlit  maximum  vijlue  ufa  IfJ-hit  integer  in  SFFFF.  If  you  du  not  leave 
enough  r(H<m,  an  err<jr  af  ftflBlW  {atrinf;  me rfiou)  will  be  returned. 

You  i:an  also  use  Hexlt  to  ennvert  a  I6-hit  unsigned  i]ite>;cr  to  a  4-byte  ASC-II 
strinii  ofht'xadpeimal  ohariietcrs.  The  diSercDcc  between  it  and  Int2Hex  is  that  the 
result  in  returned  on  the  slack; 


i  Space    for    i-esLtH  (long) 


PHfl 
PHrt 

PushUnrd  TtieHumber  ;Number    to  cgn^ert 

_Hexl t 

PopLcng  HsxFieault  iPop   the  reauil 


'Dif  first  hytes  |X3jjped  frum  the  sliitk  nrr  the  Uw-order  hcxinrleciniid  digits, 

Lnng2He'\  worU  much  like  Iiil2H('x.  The  key  diHi'renee  Is  tlhil  the  inniihtr  to 
be  eonvcrted  is  a  32-hit  unsigned  long  inlt  jipr: 

PtishLong  TheNumber  ;  Pgsh  number   to  convert 

PiishPtr   HexSlnng  ;PuSh   pointer    to   hex  string 

PuahWord  #8  iLength  o(   hex  strir^g 
_Long2Hex 
RTS 

HeicString  DS  Q  j(ltaflflard    flSCIIj    bil  7^0) 

Ntititf  (hat  eipht  bytrs  are  reserved  fur  the  hexadetinial  strins  result  because  the 
niaxinium  value  r{>r  a  InilR  ilitejler  is  SFFpFE'FFF. 
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HEXADECIMAL  TO  BLN  AKV 

Ta  convert  ASCII  strinp;s  reprf  sentinR  liexadccimal  numbers  Ui  binary  form,  use 
He'x2lnt  {ijite^eis)  or  Ht^x^Lurg  iluni;  iiilt'Err?;!-  In  both  cases,  the  binary  n-Mih  is 
retiirned  on  the  stack.  Hfrt'  is  bciw'  to  Liill  Hrx2!ntr 


PHA 

Pu^hPtr  HesNLimher 
PustiiWord  #4 

PopUlord  BinReauIt 


HcxNumbcr  DC 


C*  7EAf I 


;  space  "for  r^suLt 
iPointer   to  hex  number 
;Le!nglh  of  hex   number  string 

;pDp   the  reaul I 
;Niimbe<-    to  convert 


The  U-ngth  parameter  cannot  be  greater  than  4  since  i*n  ititeger  cannot  tsceeti 
SFFFF. 

Hex2Ljjng  converts  hexadecimal  strin|;s  to  ;i2-bit  nuiiibers; 


PHfl 
PHfl 

PushPtr  tlexMdmber 
PushUlard  #8 
_He«2Loiig 
PapLong  BinReault 


;  specs 


for  result 


HexNumber  DC 


C'OOEISOOO' 


jPointer  to  ti«)c  number 
^Length  of  hejt  string 

;pop  ttie  result 
^Number    to  convert 


The  length  parameter  cannot  be  greater  than  8  for  long  integers. 


BINARY  TO  DECIMAL 

The  binar\'-t()-detiiiial  tonviTiion  functions  iire  useful  for  transfortnins  hiniiry  num- 
bers to  the  more-recijgiiizable  decimiil  ibrm. 

lnt2Dec  converts  a  16-bit  si^n^d  or  unsiiriied  binary  number  to  an  ASCII  siring 
representing  the  nntilber  in  decimal  form.  II'  tlic  numbei  is  negative^  tlie  string 
contains  a  minus  i^ign  ti>  tSie  left  of  tlie  first  digit  in  tlit  string.  Nti  plus  sign  is 
inserted  if  the  number  is  positive,  however. 

Here  is  the  cidling  sequence  for  Iiit2Dec: 


Pu^ihWerct  TheMumber 
PdshPtr  DecStnng 
Pu^hWord  #6 
PushWord  SignedFlag 
_I  nt2Dec 
RTS 


;  The  riLiniher    to  coTivert 
jpQiiiter  to  decimal  result 
i  5  t  26  of   s  t  r 1 ng 
;0  ^  uniignetJ,   1    -  signed 


DtcString,  DS 


^ ASC 1  I    dec  ima 1  string 
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The  value  of  the  SignedFlan  piirameter  indicates  whether  th<-  number  is  to  be 
considered  signed  ur  nnsigiifd.  The  size  ul'  the  ^triiip  shcjujd  be  at  lei'.t  0  to 
accommodate  the  liinj^est  result,  Tht;  result  is  rijiht-jiistified  and  padded  un  the  Mt 
vitik  blanks.  Each  character  of  the  result  has  tlie  hija;h- order  hit  cleared  lo  (J. 
Long2Dee  works  much  as  In  tSDec  does; 

PuahLorig  TheNumber  jThe  number    to  convert 

PiiShPtr   DecSlnng  ;Poirvler   to  decima]  reault 

PushWord  t) 1  ;5ize  of  string 

PushKlord  SigncdFlag        ;0  -  unsigned,    1    =  aiqned 

_]Tit2Dec 

RTS 

DecString  DS         11  ;flSCIl   decimal  string 

The  key  differences  between  this  and  lnt2Dec  are  that  the  tiimiber  tn  be  converted 
is  a  itmg  word  and  that  the  size  of  the  string  returned  might  he  up  to  eleven 
charaeters  long. 

DECIMAL  TO  BINARY 

Most  profirains  ask  users  to  enter  numeric  Information  hi  decimal  form.  To  convert 
decimal  riumhc^rs  to  the  binary  form  the  65816  understands,  use  Dee2Int  or 
DecgLoUR. 

Df'cSltit  Cflnverls  the  ASCII  string  fur  a  decimal  number  to  a  IS^bit  unsigned  or 
signed  hinarv'  number: 

lapace    far  result 
Pii5hPtr  Dec5trS,ng  ;Pcnnter    to  decimal  string 

Pubtiklord  #S  ;Siip  of  atrlng 

Pu5tiWord  SignedFlag       ;0  =  urvsigtied,   1   =  aiqned 
_D.cc2lnt 

PopWor  d  Ei  nUord  [get    the  result 

RTS 

rj*cStriF)g  DC        C  ^Number   to  corive:r^I 

Notice  that  Dec21nt  returns  the  Ifi-bit  binar>'  resnlt  on  the  stack, 

Dcc2Lf)n^  convert!,  the  ASCH  strinfi  fo^  a  decimal  number  tn  a  32-bit  unsigned 
or  signed  decimal  number: 

PHfl  ;5pBce  -for  reault 
PHfl 

PiushPtr  DecString  jPointer   to  d*cifnal  string 

PushWord  #n  ;5iie  of  string 

faah(*lcird  SlgnedFlag  jO  =  unaignitd,    1    =  signed 
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"_DEc2Long 

PopLong  fiinLong  ^g^t  result 
RTS 

DecString  DC         C '- 31 3-82423323  '  ;Nijmber    to  convert 

Dec2L()ng  returns  the  32-bit  result  on  the  stark. 

For  hnlli  Det2Int  and  Dec2Lon^,  SiRnedFlag  is  a  Bonlean  mdic-mins  whether 
the  number  is  unsigned  (0)  or  signed  [noii?;(!ni). 
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APPENDIX  5 


ProDOS  File 
Type  Codes 


The  tiililt'  bf  Itm  iiitEic^tf  s  the  RriuTal  contents  of  a  file  with  ;i  ^^h  eii  ProDOS  file 
lypi-  L'udf,  The  stiindiLrd  ihree-ehunieter  mnrmiinies  jr=  uSuilIK  ihiHMi  only  when 
vou  C'iiUikiii  the  disk  under  ProDOS  S  or  APW.  Even  thcji.  scime  oi"  tlie  mnemontcs, 
jJiirtiLitkrh  the  oiich  lor  Apple  III  SOS  files,  iire  luit  used;  in.ste;id.  the  lie\.adeciinal 
Hie  type  eocle  is  disphiyed  to  idcilClB'  tiK'  fik  type. 


T;ihl('  of  ProDfXS  File  T>pe  CcKles 


Fih-  Type 
Codv 

SUiniliiiif 
Miitiiivnir 

Description  of  File 

m 

Untateguriaed  file 

$U1 

BAD 

Biid  block  file 

FCU 

Pascal  code  (SOS) 

m 

FT\ 

Piiseal  text  (SOS) 

$04 

TNT 

ASCII  tfxtfile 

$05 

PDA 

Pascal  data  [SOSJ 

$06 

tilN 

General  hinajA'  file 

S07 

FNT 

Font  file  (SOS) 

SflS 

FOT 

(.'.rLiphics  screen  file 

*09 

ba:i 

Business:!  BASIC  pru^min  (SOS) 

$UA 

Business  BASIC  data  (SOS) 

$0B 

UPF 

Word  pinteisor  file  (SOS) 
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htle  Type 

Stantiitrd 

Code 

Mneiiitmic 

Desci'iptitm  iif  File 

$00 

SOS 

SOS  system  file 

SOD-SOE 

[Reserved  for  SOS] 

$0F 

DIK 

Subdirectory  Ble 

$10 

RPD 

Record  Processfng  System  data  (SOS) 

$11 

RPl 

Recnrd  Processing  System  index  (SOS) 

$12 

ApplcFile  discard  file  [SOS) 

$13 

AppJcFile  model  filt-  (SOS) 

$14 

Apple  File  report  format  file  (SOS) 

$15 

Screen  library  file  (SOSJ 

Sl6-$ia 

[Reserved  for  SOS| 

$19 

ADB 

AppleWorks  database  file 

SIA  . 

AWP 

AppleWorks  word  procesiing  file 

SIB 

ASF 

AppleWorks  spreadsheet  file 

3ilC-$AF 

[Reserved] 

&B0 

SRC 

APW  source  code 

SBl 

OBJ 

AFW  object  l-ckIc 

^132 

LIB 

APW  library 

$fi3 

Slfi 

ProDOS  16  system  program 

SB4 

RTL 

AP^V  njn-titiip  linTarv 

$B5 

EXE 

APW  executable  shell  application 

$B6 

STR 

PrtiDOS  16  perc]3anent  init  (start-up)  file 

SB7 

TSI- 

ProDOS  16  temporary  init  file 

$BS 

NDA 

New  desk  actessorv' 

$Htl 

CDA 

Classic  desk  accessory 

$BA 

TOL 

Tool  set 

$BB 

DRV 

ProDOS  16  device  driver 

$liC-SBE 

[Reserved  tor  PruDOS  16  load  files] 
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File  Type 

Stamifird 

Code 

Desaription  of  File 

8BF 

DOC 

FroDOS  16  document  file 

SCO 

PNT 

Compressed  super  high-res  picture  file 

SGI 

HC 

Super  high-res  picture  file 

SCZ-SC7 

[Reserved] 

see 

FON 

PrflDOS  16  font  file 

SC9-SEE 

[HeservedJ 

$EF 

PAS 

PascaJ  area  on  a  partitioned  disk 

$F0 

CMD 

ProDOS  8  added  commttnd  file 

SF1-$F8 

ProDOS  8  USer-dt-Gned  files 

$F9 

Plfi 

ProDOS  16  file 

8FA 

INT 

Integer  BASIC  prusram 

8FB 

TVR 

Integer  BASIC  variables 

8FC 

BAS 

Applesoft  BASIC  prosr^ni 

SFD 

VAR 

Applesoft  BASIC  viiriahles 

SFE 

REL 

EDASM  relwatable  code  file 

5FF 

SYS 

ProDOS  8  system  program 

NOTE:  SOS  stands  for  the  Apple  JII  Sophisllcalcd  Operating  System, 


Appendix  □  505 


APPENDIX  6 


Memory  Cards 
for  the  Apple  IIgs 


A  slaiidsrd  cs  comes,  with  oI'RAM,  twice  the  memory  capacity  of  either  the 
Ih"  or  lie,  This  cnnfiguration  is  perfectly  fine  lor  rutiiiiiig  lle/Ik-style  programs.  It 
is  n<it  enough,  however,  to  run  the  new  cs  apphcalioiis  that  use  the  Macintosh-like 
desktop  enviroiHiieiit  provided  by  the  cs's  software  totnl  sets,  'lliis  is  because  these 
t>'pe5  f.if  progfEiins  typiciilly  need  plenty  of  menion'  to  hold  RAM-based  tool  sets, 
eiistnm  fonts,  desk  accessories,  and  so  on. 

For  some  lipplitatirins,  yoii  may  not  iiped  more  memory,  but  the  application  will 
prrfcirui  much  better  if  ymi  do  have  it.  Tlie  best  example  is  version  2.0  of 
AppleWorks-  It  uses  extra  memory'  to  increase  its  desktop  space  so  that  you  can 
have  vL-^'eral  larfjc  fiU's  npen  at  the  same  time. 

You  may  also  Wiint  ti]  aclrl  <'\tra  memory  to  take  advantage  of  Visefi.il  Utility 
prof!:rams  that  make  the  <:s  faster  anii  mnre  pleasurable  to  use.  Here  are  some  of 
the  [lljll^^  for  which  extra  memory  eaii  be  used: 

*  .A  RAM  disk 

■  A  disk-cachint^  area 

*  A  print-spooling  area 

■  A  buH'er  area  for  L'Opying  disks  in  fewer  passes 

Ram  disk  support  fur  extra  memory  is  a  l)uih-in  feature  on  the  GS.  Using  the 
Coiilrul  FaneTs  KAM  Disk  cumiTiuud,  you  eau  allocate  as  much  available  memory 
iis  voii  like  lor  use  as  a  RAM  disk, 

This  [tppendix  reviews  i^vailable  memory  cards  for  the  cs  that  plug  into  the  cs's 
memory  expansion  slot.  See  the  list  of  manufacturers  below,  RAM  memory  on  a, 


507 


card  in  this  slot  forms  part  of  the  65816  address  space,  sa  programs  van  use  it  just 
as  they  would  usf  tha  niuiiiory  core.  The  permitted  mKmury  limit  For  such 

card&  is  H  nifgahytei. 


MANUFACTURERS  OF  MEMORY  CARDS  FOR  THE  GS 


Apple  lies  Memory  Expansion 


OcloRAM 
MDltk'iis.  Jul-. 
lia^Trit™  Drive 
Fost^'i-  City,  CA  94404 
415/57:W(l5Sn 


Card 


Apple  Computer,  Inc. 
£0525  MiLriani  Avfniit; 
Cupt-rtinn.  CA  95014 
408/996-1010 


RamPak  4cs 

Orangt"  Mitni,  Inc. 
1400  N  Lukfview  Ave. 
Ajiahe-'im.  CA  92807 
714/779-2772 


cs  BAM  and  cs  RAM  Plus 


Appht'd  Enginc-iTiiif^ 
P.O.  B(ix  798 


Carrullton.  TX  75006 


214/241^6060 

RamStiikPlu^i 

AST  HL'.st:ir{.'h  \t\l: 
2121  Alton  Avenue 
Irvine,  CA  92714^49&2 
714;553-0340 

APPLE  ncs  MEMORY  EXPANSION  CARD 

Tlie  first  iiiemor>'  card  avaiUihlit-  for  the  f;s  was  Apple  s  own  Apple  lies  Mtfmon,' 
Expansion  f^ard.  It  gtime.s  with  ^.'jfiK  ttf  liA\[.  Iiut  ytju  cin  expand  it  Id  either  512K 
or  IM  by  adding  om?  or  three  additional  rows  ofei^ht  2361C3il  bit  oiemuri'  L-hips  to 
empty  sockets  on  the  eard,  (Apple  dues  not  r<." commend  a  76SKeonfiEura1ion  hecause 
some  proyranii.  cannot  handle  it. J  fhese  chips  are  iiiex|!t]iiiivf. 

The  Apple  card  is  definitely  a  "plain- van  ilia"  pruducl,  It  comes  with  no  software. 
miE  even  a  RAM  diapiiislic  program  for  teslinj:  for  Ixtd  nienmry  chips.  Ill  addition, 
it  eannnt  he  expanded  past  IM  and  you  eaiuiot  udd  any  ROM  tu  it.  Despite  tins,  it 
is  an  attractive  card  because  of  its  low  price  and  its^  excellent  owner's  guide.  The 
owner's  Kuide  clearly  illustrates  how  In  insl^ill  the  card  and  add  memor>  to  it.  und 
ii  contiiiiis  a  ii.selul  cliapter  descrihiiig  huw  to  allocate  meiJior>'  on  the  Lard  lor  use 
as  a  RAMillsk. 


APPLIED  E.\CliNEEHlNG  GS  KAM 

Applied  Engineering  is  a  well-known  nianufiictorer  ol  HAM  ciirds  ior  Apple  [I 
computers.  Its  two  main  products.  RaniFiictor  and  (for  ihe  lie  only)  RamWorks. 


have  sold  in  the  tens  of  ihnn^iands. 
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Applied  Knginrcriiij;  aL-tually  h:is  twu  .'^iii'li  urd-s:  t;s  RAM  and  GS  IL-KM  Plus, 
The  cs  RAM  uses  a,56Kxl-bit  HAM  chips  and  can  h«ld  up  tu  1.5M  of  memor\'.  It 
is  cssptituilly  thv  sanu-  us  Apple's  i-iird  hul  with  twn  extra  rt)u.s  ofeipht  HAM  sncki-t.^. 

lis  RAM  Phis  liJiiiii  >LT)  similar  lo  RAM,  liut  il  iiavs  l,C)24K>il  liit  (onL-- 
me^ahitJ  RAM  diips.  Tliis  jtieiins  that  each  row  un  the  card  holds  one  megabyte  of 
mcnniy,  sn  Hit'  L'apiitily  i)f  the  card  is  six  mciiahytes,  A  stft  of  fiphi  of  these  chips 
is  .s.till  mort'  expensive  than  the  256Kxl  ehips,  biii  iht-  lusI  is  dmpping  U^t. 

Both  t-ards  contain  an  cspansinn  port  thtit  Applied  Engineering  plans  to  use  for 
Lidding  2M  more  R;\M,  nr  ROM,  \ki  a  pi^syl^fclv  card. 

c:s  RAM  and  GS  R/\M  Pins  came  with  diagnostic  software  and  the  AppleWorks 
2  Expander  pro-am.  Th<-  Expander  enhances  AppleWorks  2.0  sq  that  it  will  work 
even  hiflter  ihiin  it  already  docs  with  us  memory  cards.  The  special  enhancements 
it  offers  ire  as  follows: 

■  More  lines  in  the  word  processor  (22,fiOO  vcrsnji  7250) 

•  More  records  in  the  databiise  (22.600  versus  6350) 

•  More  lines  in  the  word  processor  and  database  clipboard 
(2.042  versus  '250) 

•  Displa>  of  the  current  time  on  the  screen 
"  Saving  large  files  to  multiplt-  disks 

■  Up  to  a  64K  print  huffer  (versus  2K) 

•  Quick  titne  entn.'  in  the  database 

MDIDEAS  OCTORAM 

The  MDldeas  OetaR.\M  is  an  interesting  niemiirv-  card.  It  contains  eight  staiid;ird: 
SIMM  (Single  in-line  Meuinry  Module]  stK-kcts  tha,t  can  luld  il56K  memniT  modules 
or  IM  memurv'  modules.  Thus,  the  capacity  of  the  card  is  either  2M  (ci^ht  256K: 
SIMMs]  or  m  [eight  IM  SIMMs). 

A  SIMM  is  a  small  printed  circuit  card  that  has  eight  inemnry  chips  soldered  to 
il,  To  add  i!  tn  the  inemnr>'  card,  you  i^imply  clip  it  into  a  ,'iocket  on  the  card.  SIMMs 
are  new  (o  the  Apple  II  world,  hut  they  are  heirig  used  by  Apple  on  the  Macintosh 
Plus.  The  Macintosh  Pins  has  iimr  .SIMM  sockets  to  whieb  you  can  add2561C  SIMMs 
[IM  tola!)  or  IM  SIMMs  HM  total}. 

The  IM  SIMMs  ure  ciirrt'ntly  a  hit  more  expensive  than  conventional  memory 
chips,  and  they  are  more  difficult  to  find  because  they  are  made  by  fewer  munilfiK-- 
turrrs,  It  expected  that  tliev  wdl  drop  ill  pri«',  but  at  a  sluwer  rate  than  the 
l,021K.vl  RAM  chips, 


ORANGE  MICRO  BAMPAK  4CS 


Oraiipe  Micros  memory  cart!  is  called  ihe  RainPak  4cs.  As  its  name  suggests,  its 
nia.vnnuin  capimtv  is  -IM.  It  is  llit-  only  memory  tanl  thai  u^esi  25fiKs-l-bit  memory 
chips,  wliich  meajis  that  you  tan  increase  iMeiimn,'  by  2.5tiK  bv  adding  onlv  two 
chips.  This  makes  the  btiard  less  cruwdcd  than  tards  that  use  256Kh1  R,A.M  chips 
(eight  356KAlch  ips  are  n,-eedcd  for  256K).  Tw<i  25fiKx4  chips,  are  utill  more  expensive 
thun  Mght  256Kjil  thip,>.,  hiiMcvpr,  becacse  25iiKx4  Lhips  are  a  nonstandard  size. 
They  arc  also  more  diilieiilt  to  find. 

RamPak  comes  with  a  Meiiion  Manaftement  Utilities  disk  that  contains  a  useful 
and  easy-to-use  proj;riU«  that  performs  tlie  folkiwing  tasks: 

•  Memory  verification 

•  Reporting  of  disk-access  statistics 
■  Disk  caching 

This  proRfam  m.slalls  itself  as  a  Classic  Desk  Accessory  [such  as  the  Cojitrol  Panel). 
sa  you  can  call  i!  up  at  any  time  by  pressing  Control-OpenApplf-Esc-  from  the 
keyhrmrd. 

Till,-  most  interfstiiig  aspect  of  the  RamPak  software  is  its  abd%  to  enable  disk 
caching  for  any  disk  device  used  with  FroDtlS,  Cachinn  is  the  storing  of  disk  blocks 
in  Uleinory  so  that  when  a  read  operation  occ^Ir^.  iht  bt(>ck  can  he  retrieved  quickly 
from  memory  rather  than  from  the  relatively  slow,  mechanical  drive.  If  most  of  the 
disk  is  cached,  file  iiprrations  arc  sped  up  draniafically. 

The  main  advanlia^e  of  cacliiiifi  over  iLSinj;  a  RAM  disk  is  that  there  is  no  danger 
nf  losing  data  because  only  read  operations  are  cached.  Data  is  always  transferred 
tn  the  disk  when  a  write  ncturs,  Another  advantage  is  (hat  you  do  not  have  to 
transfer  files  to  the  cache  evplititly,  that  done  transparently  by  the  cacliing  software 
the  first  time  you  load  a  program  int«  memory. 

The  BamFak  software  is  ahlc  to  use  up  to  3.5M  as  9  cache  buffer.  You  tan  either 
tell  the  software  how  jimch  memory  to  use  ai  a  «achc  or  tell  it  to  allocate  memory 
dynamically. 

AST  RESEARCH  RAMSTAKPLUS 

The  AST  RamSlakPlus  is  interesting  because  it  is  the  only  memory  caid  that  contains 
socket.^  for  ROM.  It.s  maximum  RAM  capacity  is  IM  (four  rows  of  eight  236Kxl  bit 
chips),  the  same  as  Apple's  card.  [1  is  too  lud  thai  it  was  not  designed  ti>  hold  mni-e 
RAM.  hut  it  would  be  diflicult  tn  do  beeau?.e  the  ROM  sockets  lake  up  a  lot  of 
board  space 

The  R^naStakPIus  has  lour  ROM  sockets,  each  ui'  which  can  hold  a  8K-64K 
EEROM  (Erasable  Fruj^rammable  ROM]  or  a  2K-,32K  EEPROM  {Electrically  Eras- 
able Programmable  ROM),  You  will  probably  want  to  use  EEPROM  because  you 


510    Appendix  6 


can  erase  it  and  proyrani  it  simply  by  runiiin)^  a  profiram.  Vou  need  a  special 
pr()i;rLirtimini;  dt'vki'  tn  iinif^rani  an  El'HOM, 

Tlif  RamSt;ikPUis  cijim^s  v-ith  a  uliliU  pro^rain  thai  performs  diagnastics  mid 
pn)gram.s  EEPROMs.  Fru^ramminj;  an  EEPEtOM  is  simple;  all  yon  have  tD  do  is 
pill  all  thi'  filfs  you  vvaiil  to  place  in  Hif  EEFROM  hi  A  subdirectory,  then  run  the 
EEPHtJM  prii^mniniLuq  prt>)jraiii  lliat  AST  supplies. 

In  kt'L'ping  with  Apple's  standard  guidelines,  the  files  in  ROM  art"  orga.iiiz£;d  in 
tbe  H'Aini^  WAX  tUey  are  on  a  disk,  so  you  will  have  c  reated  a  ROM  disk.  If  the  ROM 
t.'0[Uaiii.s  Uie  iiet-essary  operaliii^  system  piogrinn^.  ytm  can  even  buot  Innn  ROM 
by  setting  the  Stiirtup  Slot  liii  the  Control  Panel  to  ROM  Disk.  The  hiK  differenee 
between  a  ROM  disk  and  a  RAM  disk  h.  of  course,  that  the  BOM  disk  does  not 
disappear  when  yOu  turn  off  the  liH. 

MAKING  A  CHOICIi 

With  this  analysis  uf  ca  memory  cards  by  your  side,  you  should  lie  able  tu  choose 
a  fanl  that  will  suit  yt>ur  present  and  hiture  nieinor>'  needs.  To  summarize,  the  key 
faL'turs  in  deeidinfi  what  eard  to  buy  are: 

•  The  base  price  of  the  card 

•  The  cost  of  addinjl  more  meini>n,' 

•  The  ea.se  of  adding  more  memory 
"  The  upper  RAM  hmit 

-  The  ability  to  deal  with  BOM 

•  The  availability  of  sii>ltware  utilltte.s 

Tahle  AG  summarizes  (he  features;  of  eath  memory  card. 

If  you  have  a  liniitf'd  budfjet,  keep  in  mind  that  you  tun  start  with  jiist  a  little 
R.^M  and  add  more  when  prices  drop  (or  wfien  vou  desperateU'  uped  more).  (You 
ean  buy  li^M  chips  at  electronics  parts  stores  and  itiail -order  wurehouscs, )  At  this 
stage,  you  will  have  lu  deteroiine  what  types  oE  K\M  chips  to  buy  and  where  to 
install  them  on  the  card. 

RAW  diips  are  produced  by  various  tnamifacturers  to  many  difftrcnt  siwciRea- 

tiojis,  So  you  must  he  careful  to  clmose  the  ripht  UiU^S  for  your  card.  For  US  cardj*, 
yuli  need  i\A\]  with  a  speed  specifieation  of  l5tl  nanoseconds  or  faster  thai  usesi  the 
"CAS  belure  ItAS"  rcfreshins  teehiiiipK',  Tln'  capacity  and  configuration  ot  the  KAM 
chips  is  also  iiiiportuiit;  ihe  possible  choices  are; 
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Tahic  A6:     Appk-  |[c;s  Men  iiiry-  ('iirds:  A  < 'iini|i;irisiiii  ('hart 


Prodltc! 


Mcnwnj  Minimum  RAM  Chifi 
Range  Incremt-Tit  Size 


Ilea  Mfitioo'  25Hk-lM  ■15f>K. 

li  spans  I  on  Card 

t:s  HAM 


c:s  RAM  PUis 


HaniPak  4c;s 


256K-i,5M  2,5!iK 
1M-6M  IM 


25fiK-2M 
1M-.S\I 


35f)K 


512K-4M  25fiK 


l,024Kxl 


RaiiiSlak  Plus         256K--iM  25fjKxl 


ROM  UlUUi, 
Capahilitif  Software 


3oRK  SIMM 
IM  -SIMM 


None 

Optiuii 
Op  111  Hi 

On  t-ard 

Opium 

None 


None 


Diagnostics 

A] )  pi  r  Works 
LiiliLUiccnientfi 

Ui^l^^1los^^c■s 
HOM  propramniiT 

DiaEnn.stics 


Diii.ijiuj'Stics 


•  356K\Mjit  (S  chips  =  256K] 

•  l,()2-JKxl-liit  m  v\i\p^  -  ]M> 

•  256Kx4-bit  (2  chips  =  2.56K) 

-  25fiK  SIMM 

-  IM  SIMM 

Cnnsull  your  card's  manual  to  determine  what  kind  of  RAM  thip  the  card  requires 
and  liow  many  tliips  yon  need  (t^ight  for  256K\1  or  l.C)34K.\l;  t\vo  hr  256Kx4;  or 
one  SIMM).  Ff  ynn  want  tn  pla>'  it  sufe.  order  tlit'  chips  direcllj'  IVoni  the 

L-iird's  initnufac-tLirer.  \im  will  pruliahK  pay  a  little  more,  lint  yoo  will  nol  have  liiiy 
heiidachtis. 

The  order  in  which  ytio  fill  rows  of  empty  RAM  stKketh  on  a  tard  h^iUc  important. 
If  you  do  wot  fill  the  siK-k-ts  in  tlit  prup^r  order,  the  card  will  not  work  propMly. 
Again,  consult  your  card's  inamial  for  inslalktinn  instruttions. 
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APPENDIX  7 


Disk  Drives  for 
the  Apple  IIgs 


There  arc  nine  difFerent  Apple-brand,  rem nv ah |p- media  disk  driven  yiiu  t-an  uac 
with  the  Apple  llCS;  five  5'/i-ineh  drives  and  four  ^Vj-ineh  drives.  This  dppenJiv 
looks  al  each  ol  (hem  and  examines  how  to  use  them  with  the  CJS. 

5'/4-INCH  DISK  DRIVES 

Tlie  nriM'nal  drive  for  the  Apple  fl  was  [he  Disk  II,  firsl  relcast-d  in  1979,  It  vvitrks 
with  140K  5'/i-i]ieh  floppy  disks  and  eiimt  s  with  a  permanent  eable  that  te;rmiiiiltc;^ 
in  K  20-pin  rectangular  connector- 
Apple  no  longer  ^tUlnufaetll^e^  Ehe  Disk  IT.  hut  the  companv  ha*  four  other  5W- 
inch  drive*;  to  replaec  it:  the  UniDisk  5.2i'5,  the  Apple  5.25  Drive,  the  Disk  He,  and 
the.  DiioDi.ik.  (The  Apple  5.2-5  Drive  is  the  same  as  the  L'niDisk  .5.25  eseept  tor  its 
t;s-Iikt  platinum  enlor. )  The  drive  meehanism  in  t-aeh  of  these  drives  is  functionally 
equivalent  to  that  of  the  Disk  II,  su  all  of  Ap[>le\  5V^-inch  drives  read  and  write 
thie  same  disks. 

'iTie  DuuDisk  is  uniqtie  in  that  it  contains  two  drives  in  one  box.  The  UniDisk 
5.25.  Apple  5,2,5  Drive,  and  Disk  lie  are  all  one-drive  devices,  Eath  of  these  drives 
has  the  same  type  of  ennneetor  eable,  however — one  that  (ennbiates  in  &  D-sbiiped, 
19-pin,  male  DB-19  eonnettor. 

Yuu  can  eonneet  two  [but  no  more  than  two)  UniDisk  5.25  or  Apple  5,25  drives 
together  by  atladiinj?  the  second  drive  to  a  connector  on  the  back  of  the  first  dnvc. 
This  inethod  of  tomiectln^  multiple  drives  is  tailed  daisij-chaining  and  is  Apple's 
'ofRdal'  techniijue  lor  attaching  nndtiple  drives  to  a  system.  BerAii.se  a  DuoDisk 
contains  two  dri^  es,  it  does  not  have  a  dai^y-chain  conneLtor;  nor  do  the  older  Disk 
li  or  Disk  He  drives. 
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VA  ISCH  DISK  DRH  ES 


In  1&85.  Apple  slarted  selling  a  3'/2-iiich  drive  for  the  Apple  11  called  the  UniDisk 
3.5.  This  Is  a  very  inlelligenl  devkf,  c-oiil^iniii^  a  65C[I2  microprocessor  and  a 
program  in  HOM  ihr  laii trolling  disk  Jala  Iriitisfers,  It  uses  douhle-sided  800K  hard- 
shelled  disks  for  media  and  works  with  any  Apple  II  model  [extept  older  Apple  lie 
systems),  The  UiiiDisk  3.S  cable  has  the  same  DB-IQ  eotniector  as  the  cable  fnr  the 
UniDisk  5.2-5  and  the  DuoDisk- 

Whcii  (he  CS  was  yniiount'cd  in  St'ptrmbcr  another  SVs  inch  drive  was 

unveiled,  the  Apple  3  5  Drive  It  works  with  the  same  800K  disks  as  the  UniDssk 
3.5  but  does  not  have  the  built-in  intelligence  of  the  UniDis];  3..5.  It  works  only 
with  the  GS  or  the  Macintosh.  The  main  advantage  of  using  an  Apple  3.5  Drive 
instead  of  a  UniDisk  3.5  on  the  cs  is  that  the  Apple  3,5  Drive  operates  shghtly 
faster. 

The  other  twu  Apple-hrand  3'/>inc:li  drives  thiit  ean  be  made  Ui  wnrk  with  the 
GS  are  the  standard  4tJ0K  a.nd  HtXJK  e-xtt-mal  drives  for  the  Maeintnsh.  To  us,e  them, 
you  must  have  a  Univer.sal  Diik  Ojntrniler  (UDC)  frum  Central  Point  Jiuftware 
[9700  S.W.  Capitol  Hwy..  #10(),  Portland,  OR,  97219  1.503/244-57i4aJ);  more  infor- 
mation on  the  UDC  is  provided  hekiw.  The  UDC  also  works  with  all  other  Apple 
drives  [cvcept  the  DuoDiak)  and  with  t^ne  non -Apple-brand  3'/a-meh  drive,  thc.SOOK 
Chinon  3.5  drive  sold  by  Central  Point  Suftwore. 

USING  DRIVES  WITH  THE  APPLE  Ucs 

The  GS  has  slots  like  those  on  Uie  He  and  built-in  peripheral  ports  like  tho^e  on  tlie 
lie.  To  select  whether  a  pori  or  its  eorrespo'ndins  slut  is  active,  use  the  Slots 
command  in  the  Control  I'anel  desk  accessory.  You  c-an  call  up  the  desk  accessory 
menu  at  any  time  by  pressing  Control-OpeiL^ppIe-ESC- 

One  nf  thr  bnih-in  ports,  cnrre.sponding  to  slot  5,  is  a  disk  drive  port  called 
Sniai  tPort;  it  i.s  designed  to  handle  3V2-inch  di'^k  drives  and  any  intelligent  periph- 
erals that  use  the  data-exchange  prntocol  and  electrical  specifications  defined  by 
SmartPort.  The  SmartPort  connpctnr  is  a  DB-19  type  and  is  located  at  the  hack  of 
the  Cs. 

Another  built-in  port,  carres ponding  to  slot  fi,  ls  the  5W-inch  Drive  Port.  It 
shares  the  same  phy.sical  etmneetor  RinartPort — this  does  not  cau.se  problems 
because  S'/i-iilch  drives  can  be  dai^y -chained  to  SmartPort  devices. 

You  will  probably  want  to  daisy-chain  drives  to  the  SmartPort  instead  of  using 
plug-in  controller  cards.  Five  types  of  drives  can  be  chained  tn  the  SmartPort:  the 
UniDisk  3.5.  the  UniDisk  5.25.  the  Apple  5.25  Dri^  e,  the  DuuDisk,  and  the  Apple 
3,5  Drive.  (You  can  also  use  the  Disk  II,  but  only  if  you  have  a  special  adapter  cable 
made  up.)  I|  is  itnportaiLt  to  understand,  however,  that  you  cannot  chain  these 
drives  m  just  any  order. 
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If  yuu  are  usin^  Apple  3-5  Driven,  ihcy  must  appear  at  the  Ix'^iimmR  of  the 
thaiii,  befbrtf  anv  liiiiDi-,k  3. .5  Jdves  or  SV^-inch  drives,  You  ciui  up  tti  twn  i>r 
these  types  of  drives. 

At  tiiL'  cikI  of  the  chain  come  tlie  SVj-infh  drives:  up  to  two  UniDisk  5.iS  drivt-s 
(ir  ime  DuoDisk  (which  is  cfiuivaWul  In  hM>  UiliDisV  5.25  drives)  miiv  be  used. 
Tlien^  is  one  t-aveat  rir'latint!  tu  llic  DuoDisk,  liowcvcr— lietaiise  !)f  a  hardware 
prublein  in  the  drive,  you  caLiiiol  daisy-chain  a  DuaDisk  having  a  serial  number 
l>e]ow  433754.  Apple  hus  piiliH^lifd  a  tet-^iriical  note  descrihing  a  hardwbire  fix  to 
solve  [his  problem,  so  tratk  it  down  if  you  want  tt>  use  mi  uJd  DuoDisk  with  the  GS. 

Betwc-en  the  Apple  3.5  Drives  at  the  heginninK  c»l  the  chain  and  the  UiiiDiiik 
drives  at  the  end  of  the  ehain  ctmie  any  UniDisk  3,5  drives.  The  nnmher  of 
UntDisk  3.5  drives  is  limited  bv  the  eapatiu  of  the  ca  power  supply.  Apple  rec- 
oimnend^  that  you  hiive  ciu  more  than  four  drives  eonnectcd  to  the  SmartPort 
[including  anv  Apple  3. .5  Drives  and  SW-inch  drives),  althouj^h  thf  GS  seems  tu  be 
ahle  tu  handle  six  cjuite  %v*-ll. 

Keep  in  mind  that  no  other  orderiiig  of  drives  will  work^  the  order  must  be  Apple 
3.5  Drives  folbwed  by  UniDisk  3,5  drives  follu^ved  by  o'/i-meli  drives. 

The  ProDOS  fl  (fperatins  system  requires  that  disk  devices  lie  mapped  tu  tradi- 
tional slot/drive  combinations  with  mo  more  than  two  drives  per  slot.  How.  then, 
does  it  deal  with  the  possibi]it>  that  morr  than  two  drives  may  be  chained  to  the 
slot  5  Smart  Port':" 

The  way  ProDOS  S  assigns  slot/drivc  cimibinalions  to  SmartPort  disk  drives  is  a 
bit  unusual-  In  inuHt  sitiiaticms,  the  first  four  3'/2-ilieh  drives  arc  eonsiJered  to  be 
the  slot  o/drive  I,  slot  .^/drive  2,  slot  2'drive  1,  and  slot  i'drive  2  devices.  The  two 
5V-i-inch  drives  on  the  Smaj-tFort  correspond  to  slot  6/drive  1  and  slot  6/drivc  2. 
TliLiI  is,  cminet  tinKtheiTL  to  the  end  of  the  SmsirtPort  chain  is  the  same  as  connectins 
them  to  a  eunlruUer  tard  in  slot  6. 

If  you  use  the  CS  Control  Panel  to  define  a  system  KAM  disk,  howev  er,  the  slot/ 
drive  assifinint-nts  are  scramhled  sli^^htly,  The  first  3V2-iiich  drive  is  still  the  slot  5/ 
drive  1  device,  l>iit  the  IKASi  disk  k  as^iRned  as  the  slot  S/drive  2  device  The  next 
two  3'/2-mch  drives  ■'oeeupy"  slot  2/drive  L  and  slot  2/drive  2.  Any  other  3Vi>4neh 
drives  are  not  retotlnized  by  ProDOS  S, 

ProDUS  16,  oi)  the  other  hand-  does  not  retiuire  slo^drive  assifjnnietits  and  will 
work  with  any  number  of  disk  devices  without  diffieutty, 

li  you  wish,  you  can  also  use  eillier  of  the  two  standird  Apple  oVj-ineh  disk 
cnntruller  cards  on  the  GS.  if  you  put  the  cnntnjfler  Lard  in  slot  5  or  6,  keep  in 
mind  that  you  will  not  he  able  to  use  the  fSmartPort  or  the  Dri\  e  Port,  rcspectiveh-. 
You  fjim  also  use  C^entral  Point  Snftware\  UTii\  ersal  Di^ik  C^ontroller  on  the  CS.  It 
works  with  alnit).st  any  tvpe  of  5'A-inth  and  3'/2-iiicli  drive  availi\ble  for  the  CS, 

Tiie  Chinon  3,5  drives  the  UDC  works  tliLil  are  also  sold  by  Clentral  Point 
Software-  The  only  majiar  differences  between  them  and  Apple's  3'/;-ineli  drive.^  are 
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that  they  dn  imt  hav*-  daisy-tliain  conin-ctors  iincf  thul  ihtr  disk  eject  biittnn  is 
completely  methaniral.  iThcre  is  Lin  c-lcctraiik-  disk  pject  incfchanism  thaE  is  con- 
trolled by  the  Siinii.-  Jioftwar*'  cuui mauds  the  Apple  3'/a-iiieli  drives,)  The  Chimin 
drives  also  work  iiitely  as  8<M)k  exlt-rtial  drives  for  the  Maeiiitosli. 

A  nitf  feature  of  the  «r;s  is  that  yiiu  can  use  (lit?  CnntroJ  Pmiel  to  specify  the  slot 
of  (he  drive  frnm  w  hich  tti  biKil— this  is  ealled  the  Stiirtiip  Slot,  "[lie  default  is  "SeaTi," 
which  means  that  the  c;s  \vill  boot  ironi  t\w  firsi  drive  it  OfK-oiiiiters  in  a  ^eareh 
ficg;inning  in  slot  7  and  iiuix  iiig  down  tu  slot  1  {this  is  tlie  nit-tliod  jsecl  on  the  He), 
Only  the  first  drive  in  each  sht  or  [xtrt  is  wjnsicSered,  howcvFr,  so  you  cannot  boot 
frnm  a  setondttry  drive.  If  yciii  prefer,  you  ean  ti.  \[  the  cs  to  boot  fniin  a  i;iven  slot- 
specify  slot  5  tti  boot  Ironi  the  first  ^'A-iiich  drive  Wmneuted  to  the  SmartPort,  for 
example. 
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APPENDIX  8 


Resource 
Material 


If  voLi  arc  interested  hi  flf  \  rltipiiis  snftwan^  on  tlie  GS  y.m  should  Inecome  a  iiieinbpr 
of  AFDA,  the  A|iple  Pn>E;raTiiiiier  s  and  Developer's  AsscK-ialion.  Its  address  and 
telephone  numlier  are  as  follows: 


Apple  Programmer's  and  Developer's  Associatinn 
29Q  S.W,  CJr-d  Street 
Reiitnii.  WA  98(>55 
2()6/2gi-&^8 


APDA  is  an  asstJtiiUioii  that  wii^  crfatrtl  liy  Apple  CTumputer,  Inc.  in  AurusI  19fi6- 
It  is  adniiTiiitered  liy  the  Applf  Yu^i-t  SLiiind  PrtigraiTi  Lihrar>'  Exehan},'e  Co-oper- 
ative Assndatioii  {A.P.P.  L.t,  Co-op)-  The  priinary  fiiiietlun  of  A  PDA  is  lu  diwm- 
iiiatf  prerelease  vcrsiimi  ol'  offici^il  Apjile  pmnraini]iiKiT  iiifortnatifHi  ior  the  Apple 
K  [ind  MaLiiitosli  fLiiuilies  ol  t-nmputers.  Tliis  ]iK:ludeS  technical  referente  manuds,, 
teehiueul  notes,  and  software  developiiienl  tuoK  AFDA  i.';  aisti  a  eonvenient  aiturce 
of  nOii-Apple  scti'twarf  und  hiioks  for  software  devt-lopers. 

Th*-  advantage  of  joining  APDA  is  tliat  you  can  gfti  your  liajids  on  useliil  tcehnieal 
infonnLition  qnickly,  Win  do  nol  have  to  wait  for  the  information  to  be  polished  and 
published  in  fiii;Ll  fonn. 

DEVEUJPMENT  SOFTWARE 

To  devclnp  .sttftwiire  on  the  CiS,  you  will  prohaMy  wjnt  the  Apple  Hc-s  Pn!f;rammer's 
Workshop  (APW'l.  which  is  available  frdiu  Ai'DA  {st;e  iiboveK  The  Imif  APW 
paekage  includes  an  editrvr,  fi5Sl6  ass<'mhler.  linker,  and  several  support  prrigrams 
you  can  use  to  creatp  pniRrinns  thai  run  uiidiT  PmDOS  16.  The  !>lKLial  APW 
developoieiit  system  is  almost  identical  to  the  OBCA/M  system  available  from  Tlie 
Byte  Works  Inc.,  #£07— ITfX)  Ir^in;;  HKd.  N\V,  Alhnt|uerque.  NM,  87114  (fjOia/NHS- 
filH^l  This  is  betansr  Tlie  Byte  Workii  developed  APW  lor  Apple. 
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Another  altt-rnativt.^  tiS  assembler,  whidi  cli>es  not  reriuirt;  APW.  is  Mprlin  H\6 
from  Roger  Wagner  PuhlisliinH.  fiit-.  (1()50  Vkmt-cr  VV;n    Suite  P   El  Cajon  C\ 
92020  [619/442-(l.522]).  It  conits  with  a  li.krr  winch  is  ..p:ibl.  of  creating  .land^rd 
ProDOS  Ifi  applications. 

Applf  also  distribules  an  AinV-cnnipaiible  C  compiler  idf  velopf-rf  bv  .MegaiTjax. 
JnL'.]  which  geiierattrs  olijjptt  code  in  tht  fonmt  expected  by  the  APW  linker. 

All  APW-cotnpatible  Pascal  tompiler  is  available  from  TML  Systtin^  (#23-4241 
Baymcadows  Road  JacksonviHr.  FL,  3221V  [9(U/fi36-S592|),  TML  alio  sells  a  stand- 
alone Pascal  ctunpiler  thai  ii.se:s  iht-  standard  dt-sktop  t-nviroiniicnl  of  the  gs. 

MACINTOSH  CROSS-COMPILERS 

You  win  also  develop  f,h  lipplicatioiiK  usinfi  crn.ss-enmpiters  on  the  ^^adn^osh,  Tlie 
advaiitapt  of  doinj;  this  is  pniiiarily  ipeed:  wnnpilation  linies  an?  nian^'  faster 
when  periormed  by  the  Maiintoshs  68001)  miemprutfssor  llian  when  nvdonnvd  bv 
the  cs  s  less  powcrfu:  RSSie. 

Cunsulair  Cnrp-  (140  Carrip<j  Drive.  Portola  Valley,  C.\,  94025  [415/H,Ti-3272]J 
5clk  tlic:  MACtnGii  Assembler/ Linker  systejn.  It  assembles  and  links  APW-cor^pI^ 
iMe  65filR  assembly  laogoase  Mnirc^  L(«le  files  on  a  Ma<  inlosh  to  creatr  compI*^te 
t:s  applitations.  OfcoursL..  to  nin  the  applitalions.  vou  must  first  transfer  ihem  tn 
the  cs  (osing  a  cnininunieations  program  or  Apple    Passport  program). 

TML  Systems  [.^w  above)  has  a  Pascal  cross -eompilcr  that  seneratci  65M16  somte 
code  files  that  can  then  be  processed  by  Consulair's  MACtoCS  Assembier/Linker, 
You  can  imy  the  etjmpiler  fi-nni  TML  separately  or  with  the  MACtnGS  Assembler/ 
Linker  included.  Another  Pascal  crnss -compiler  ii  available  from  Megamax  Inc 
[Boa  ^51521,  Ridiardsoii,  T\,  73085  I214/ft87-4y31j}. 

Megatnax  also  has  a  C  eross-coinpiler  which  works  with  ttic  same  sonrce  code  as 
the  version  of  C  it  developed  for  APW  does. 

REFERE.\CE  BOOKS 

The  many  books  ynn  will  find  ustrfid  for  teaching  yoursdf  how  to  prosram  the  US 
fall  into  four  categories: 

•  GS-specific  bi.Ktks 

At  the  present  time,  nio^t  of  these  liooks  have  been  vvTitten  bv  Apple  Com- 
puter. Inc-  Thosf  that  arc  not  yd  in  final  liirin  are  available  from  APDA 
When  completed,  most  wil!  be  published  and  distributed  by  Addison -Wesley 
Publishing  Company,  Inc. 

•  Books  about  the  lie  and  lie 

These  booki  will  assist  yon  in  developing  Iraditiojial  applications  on  the  GS. 
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»  General  books  on  programming  in  65816  assembly  languagt; 

'  Books  about  thf  MiiL'intosli 
These  Iwuks  arc*  useful  because  they  describe  general  techniques  for  program- 
ming in  a  desktop  environment, 

Books  for  the  Apple  lies 

Apple  Computer.  Inc..  A/jp/t-  llcs  Finnuart'  Reference  [Beflding.  MA;  Addison- 
W'esley  Ptibli-shing  Company.  19871. 

Apple  Ctnnpuler,  Inc..  Apjitv  liardicare  Refewiue  (Readins.  MA:  Addi^m- 
Weiiley  Fubliirhiiii^  Ctimpiiny,  1987). 

Apple  Computer.  Tnc,  Apple  llcs  ProDOS  W  Reference  (Reading,  MA.  Addi- 
son-Wesley  PubUshinjj  Company,  Inc..  19S7). 

Apple  ComputLT.  Inc.  Apple  llcs  Tot/lhox  Reference,  volumes  1  and  11  (Read- 
ing, MA:  Addis on-Wes ley  PiibUshing  Cooipauy.  1988), 

Apple  Computer,  Inc.,  Appln  Programmers  Workshop  Assembler  Reference 
[Cupertino.  CA:  Apple  Computer,  1987), 

Apple  Computer,  Inc.,  Apple  Programmer  s  Workuhop  Reference  (Cupertino, 
CA;  Apple  Computer,  1987!. 

Apple  Computer,  Inc.,  Human  Interface  Cuideffrtcs  (Readinj^,  MA:  Addison- 
Wesley,  ISST). 

Apple  Coiiipnter.  Inc.,  Prngramtner's  Ititrodiirtion  tu  the  Apple  Ilci>  (Reuding, 
MA:  Addison -Wesley  Publiiihins  Conipaii)',  19SS). 

Apple  Computer,  Ine, ,  Technical  Intritdiictioit  to  the  Apple  l!es  (Reading,  MA: 
Addison -Wesley  Publishing  Coiup:iny.  19^6). 

Fischer,  Miuhael,  The  Apple  Ilax  Technical  Reference  (Berkeley.  CA:  Osborne 
McCraW'Hdl,  1987). 

Wagner,  Rofirr.  Apple  Ht;s  Macliinc  Lunguag,e  fur  Bee,inners,  (Greensboro.  NC: 
Compute!  Puhbcations,  19871. 
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Books  for  the  Apple  Tie  and  lie 


Apijk'  Computer,  Inc.  Ajv^/r  ilr  TechnWal  Reference  Manual  {Reading,  MA; 
A  (id  i  Sim -Wesley  Fllllli^llilln  CVjiiipLiin .  19.45). 

Apple  CnmpiitLr.  Itu-,,  A,,pU:  Ui'  Tvvhmtul  Hvicrt-nn'  \hnu,a}  (Rt^adins,  MA: 
Addistm-Wpsley  Puhlishinjj  Cimipany,  lyyS) 

Apijlf  t:omputer,  lut..,  Appia  Smnvhcs  Manual  iRoadiii^.  MA;  Ad<li^(Ki.\\>s|cv 
Piihlislimg  Company.  I9S6). 

Unlv,  C^r>'  B..  Afjpli^  ProPOS:  Aih  ftiici-d  Feattiir^  for  Fwgrammers  (Bowie, 
MD:  Brady  CoinimiriiLiLtiiins  Ctmipaiiy.  19S5). 

Apple  C:oinpiiU>r,  Ifil..  ProDOS  Technical  Reference  Manual  [Readinj^.  MA: 
Addison- Wesley  Publisliing  Ci*nipiiiu,  IHH5). 

Little.  Gary  B..  !.,m{c  ihe  Ap)jle  tic  {BuwLt-,  MD:  Brady  Commiiiiicahons 
Ccnjipany.  19S5), 

Little.  Glut  B  ,  Imitip  tlw  Apple  !h-  fBuwic.  MD;  Hradv  Coniniunic-ations 
Comp:iiiy,  lybo}. 


Books  on  6bS16  Asisiqmbly  Langua^t-  Programming 

Eyes.  David,  and  Ron  Lieht>-,  Prnfimmimns  the  65810  Indudinp:  the  6503 
<i5C02  (mil  fi.5S05  (Npu  Vi,ik:  Prentice-Hall.  1986). 

Fischer,  Michael,  6.i?il6fmm2  Assrmbhj  Lancuaiic  Prafiramminfi  [Berkeley  CA- 
<J.sl]onit'  MeCruu-JliJI.  ISJSfi), 


Bwtks  for  the  Maanlosh 


Apple  Computer,  Int.,  Iiiside  Macintosh,  volumes  L.  11.  Ill,  and  1\'  (Reading, 
MA:  Addison -Wesley  Publishing  Company.  1985.  I9S6). 

C:hernic(ift;  Stephen,  Macmiosh  Revealed:  Vnlockinf^  the  Toolbo:^  (Indianapolis 
IN:  Haydrn  Book  Company,  I9fi51. 

ChprnienFT.  SlLpln  ti,  M^irmtotth  Rvvealfd:  Proaramminf'  uith  ttw  ToolLux  [In- 
diiuiapolis.  I\;  Hindeii  llottk  Compani,  19fi5), 
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Little,  Gary  B- .  Mac  Assembly  Lartfiuflgf,-  A  Guide  Jor  Programiiurrs  (Nt-w  Yurk: 
Prentice-Hall,  1986). 


MAGAZINES 

Magazines  are  the  best  source  of  informatinn  un  what  softwure  and  hardware  pnid- 
ucts  are  currently  avuilahlc  for  the  cs.  Many  uf  the  magazines  that  arc  aviiiluble  an- 
written  for  .\  general  aiidieiK-e,  but  some  nfe  clf^aTly  for  programmers  only.  The 
OJIOS  marked  with  an  iisterisk  in  the  lullowiiig  list  are  the  ones  pri>firi!iiniliers  wilt 
find  most  interesting. 


A  + 

U  Davi^  Drive,  Belmuiit,  CA  94002 
415/598-2290 

*A}}ple  As^emhhj  Line 
P.O.  Bos  2H0300.  Dalliis.  TX  7S228 
214/324-2050 

Call  ^A.P.P.L.E. 

290  S.W.  43rJ  St.,  Rciitcm.  WA  98055 
206/251-5222 

inCiden  The  Apple  11  Magazine 

fiO  Elm  Street,  PeterhurouRli,  NH  03458 

603/924-9471 

*MacTntf}r:  The  Maciniosh  Programming  Journal 
P.O.  Box  400.  Flac-entia,  CA  92fi70 
714/6.30-3730 

*Nibh!e:  The  Magazine  for  Apple  U  Enthttftiasts 
45  VVinthrnp  Street,  Concord,  MA  01742 
6l7/371-lf)fU) 

*Optn  Apple 
P.O.  Box  7651.  Overland  Parle.  KS  66207 
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INDEX 


65M16  jTiii.T[i|>nit.tsiiar    J-2.  I'-i  ff. 

addressinji  OMidfs  3U 
L'Vtk-  time    22,  50 
ftiiLiliilkiEi  iiiudi:-  1 
instriKliuii  ninemciik-'i  5f) 
iiLstruclioii  uiiL-odi-ti  50 
in^trucliiin  wt    22,  5(J 
iiritivE-  mocU'  1 
leKisters  15 

EpLLifi nation  shtft    471  j^, 
^TJs^d    2.  i:j-14,  22 
8330  scriii!  tummunicBitnins  c"n(TiJ'llt'r  5 


A  refjistfr  2(1 

Abort  iiilfrriipts    37.  .19 

ARSADDR  ilirL-iliu-  47 

jilisntiitt  iiijdroMnji;  iiii)de  !i5 

iibsulutt-  iiidi.\t.d  acldi  t'ssinn  mod*"  3.'5-'16 

ahi^cliiti'  liiii^  dddrL-^siiij^  iiitxlc  35 

actejis  todc  (PniDOS)  33fi 

nccnmiilatnr  20 

at'LLJiiiiiSLitGr  tiddix'^isini^  [node  32 

atliv^k-  i-M-iiI     12:5.  12^  141 

ii(.-li\e  vviiitliivv  16] 

ADB    ¥fc'  Apple  DeskTop  Bus 

iidditioii    ^0,  27 

cfTcirt  iil  i-jm  fljt;  17-lh 
eBett  ol  deciniLd  mod*:'  flaj^  18 

dddrfjis  spuee    2,  14 

ddtlrf  ^sjii^  ini'di-s  31) 

biLt'iiniiiliitEir  32 

block  inniie  34 

(lircLt  pagi'  35 

liirftt  pa^f  iiidfSL'd!  35-36 

immt'tliiite  32-33 

implied  30 

iiitflrLL-t  36—37 


pnifiram  L-ourKer  rolotive  33 
program  (JDunfer  relative  long  33 
stack  33 

stuck  reliilive  33-34 

stink  reliilivt'  indirect  indexed 
vrith  V  34 
APSR  env^-lope    4DH.  410-411 

Etefinitinn  412 
Alerl  2HH-2H\} 
aleit  boxt's    lUTff..  jf. 

di'iiiull  liuttori 
iilsTt  template  2fi9 
AllXotcsOfl  414 
AlkK-C:fii    407-109,  415 
ALLOC.lNTF-nnUPT  39.360-361 
Altcmiatc  Diipl»>  Mfide  [HTf-sun  2. 
106,  311 

analoi^-tu-digital  conversiuTi    10,  3ati.  407 

AND  iiih.truDlion  '2b 

AND  inask  43"-^ 

A  PDA  517 

appending  Files  352 

Aijpk-  Hl    1,  13 

AppW  lie    I,  13 

Apple  lies 

annoiincenient  ty(  I 

credits  12 
Apple  DeskTop  Bus    7-8,  125 
Apple  menu  247 

Apjiltf  Prtigrairimer's  Workshop    11,  12, 
40-41 

selecting,  a  language  40 
Applcsof!    2.  104,  KJ^ 
A[ip]etiilk  3 

meiinon'  usa^n  10-1 
applications,  fiTafing  49-50 
APW    see  Appfe  Program mci'  s  Workshoji 
arithmehf  instni-ctiOnS  27 
asLtriil  197 

ASCII  character  codes    129.  ^99.  463  J^T 
ASL  instruct itiii  29 
ASML  command  50 
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attributes  (memorv  hlDcks) 

bank-houndury  iLmilc.-d  !13 
bliK-k  I11-112 
fiKed    112-113.  115 
fixed  H(Idrt's.f  114-115 
fi-vfi:!  biLiik    1 14 
hvked  112 
pa^c-^ili^ned  114 
purfif  It^vel    1 13 
si'ltinK  lis 

ipeciiil  int=inory  not  iisabli?  113 
audio  wavffonn  392-.'iSJ3 
auto-key  evcjit    129,  140 
au.viliur>'  meinory  2 
iiiixiliaiT  typf  tiado  (ProDO'S)  341 

B  register  ^ac■c■ur^lJii^tor)    20,  2.5 
B  rt-Ki-iter  (data  hank)  21 
hink^roLiiid  tolor,  te%t  SLTi?cii  9 
hiuiks  son  and  SOI  106 
bdnks  SEO  ;iiid  SEI    1G2,  KM-ltt'S 

bllSfllllE:  197 

BeKinl-'pdatf    17S-180.  31V 
binary-LiJtled  deLjuiiil  I^i 
binari-to-hcv  ftjnvcrsirtn  4&lfj 
BIT  instruthon  2H 
hi  t-inai  lip  Illation  inhtruLtions  2fi 
bloL-k  move  addrt-ssinp  nnxie  34 
blix  k  movt  imtmcliiiii'.  25 
h\tKM  rpcurd    ILCI,  ]  17~11S 
hlHjr]i-stmi.-titred  devices  3315 
BlockXJ.ivf  120-121 
blixfc  110 

alloLUtinp;  Ufi-117 

disposing  II6-11U 

moviiig  12.tK121 

pui-Ring  11«-II9 
Boolean  t,hin  typf  75 
Boollriit  hintlifin  79 
border  ttilor  9 
Bull  nds  Rett  171 
brarifh  in  str  net  ions  26 
brti^ak  flag  18 
BRK  iiistriu-tiDii    IB.  3S.  4tl 
busy  ilajf  ^jl 
Button  128 


bullun  (dialog)  273-274 
Jefaull  274~275 

C  compiier  12 

C  register  20 

CulcMenuSii^e  250-251 

carry  flag  IT-IS 

CautiunAlert  2Sfi 

C  H  A  N  G  E  _  F.-^TH    -54  2;-  34  3 

^'banncl  ^iddress  396 

fharatter  device?  330 

cluir^cter  VO  4^ 

tiidrac-ler  oriyin  1EJ7 

charac  U-r  reclauKl*^  19S-197 

L-hiU-llL'StTS 

how  to  draw  199-201 
CharWidlh  mi 
check  biwes  275 
Clifc-kVlIteiii    24^*.  251-252 
f 'hoo5ei""t>n  t    1  ^4 

Clasijic  Desk  Accessories    2.  4,  5  70-71 
■-311//- 

instathticm  313 
CLEAR_UACKUP_Brr  344 
diiikinjj  67 
dipboarti    73.  244 
flock  funetions    14-1  Jf 
cliK-k  speed    102,  105-106 
diwki'calrndar  H 

CLOSE  :^5(^ 

elose  boK    169,  176.  IS5 
CloseDiaJog    2H^.  2h5 
CloseN  DAhyW'iii  Ptr  314 
ClosePtiK  207 
ClosfWiiidow    175,  182,  1S5 
vUismj;  filos  -3.50 
color  labJt"    1(33-164,  11^,  273 

for  a  winduw  177 
colars 

for  pittems  IHh 

for  pen  1^7 

standard  167 
ct>mniDiit  fifid  42 
comoieiit  lines  41 
compai/titm    I10-II2,  115,  117 
Oi  111  pile tM tin    1 10 
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coinpsirtnB 

effpft  im  ciirrv  Rag  Jfi 

effptt  on  lljsi';  26 
KmipariSLiri  iii^lruL-tioiiK  27— 2fi 
LiiTTpti'iiU"  vulfi,!  port  7 
(.■ynditkiiurl  asscmWy  49 
(xiTislaiil  dcfiiiitiofLS  -lC-47 
coiik'iil  rtsiiHi     16],  liiH 
t-ontriil  chaiutlf  463 
Ciintrol  Mbiniiger  72 
Control  Panel  actcssory    2,  4,  B-7,  VO- 

71,  311.  330 
t-ontrob    72.  I(i8 
COP  instnic'tion  40 
CUPY  directive  42 
CP/M  II 

CnEATF,    ■IST-a'Jfi,  343 
CTeiitiiiR  tiles  'i'iY 
creation  dale  341 
creLitiiin  time  .14l-.)42 
CSfrini^Width  201 
cursor  (^riiphics)  141 

mask  1-12 

record  141-142 
cursor  (test  screen  )    445^  447 

hofiziiiitil  position  447— US 

pDsitioiiiiig  447 

position  447-44S 
cycle  time  22 

□  re^^lf^r  £1 

tiatii  ulliir^tion  flireetives  46-47 

data  bajiJc  rcj^ister    21.  35 

(jata  iiiaslu  437 

diitii  types  75 

DblTinic  paranieter  13S 

DC  clirtLfiv.-  4G 

Dedl.K.<;c-ii    41 1 

DEALLOr_lNTERRUPT  361 

Dccilril  500 

Dei.-21.oni;  ^ 

rfpt'imal  mmie  HiiK  IS 

deeimal-to-biiia)^  tonversio]i  500 

dt'ercniixUiiiR  27 

DfleteMriiii  253-25-1 

DeieteMltem  251 


delctinic  tiles  342 

dt  rt'ftTi'nciiig  handles    114-1 15 

deNcenl  197 

desk  atrcessori**s    70,  255.  311  ff. 

and  Menu  Manager  24S 

louding  333 
df*k  acfpssiirv  eveni  12.B 
Desk  Manager  70 
DeskShutDown    312-313,  316 
D*-skStartLii    312-313,  316 
DeskTop  Bus  Too]  Hel  71 
desktop  inetaphoi  67 
DESTKOY  342 
dfi'i'ktpmerjt  softwiire  517 
devicf  driver  436-437 
device  driver  event  129 
device  name  34^ 
diiignostpcs  2 
dialog  botes    267  ff. 

how  to  use  '2fi3ff. 
dialiJg  iteniS  271-272 
Diali>p  Maiiflgcr    73,  267 
Piuli>KSt>lfL-t  2S7-2SS 
DialosShulDown  269 
DialogStartiip  26^-269 
DiRit^  Ostillator  Chip    10.  71.  73.  389, 
392 

address  refji^ter  395 

analog- to-di{t;i  till  register  399 

enntrol  register    395— J!3fi 

data  rt'pslor  395 

freqiiencv  reKisltr  395 

osfilktor  enable  regist<^r  3!)H-3!)9 

Osrillalor  inLt-rrnpt  register  .39B 

registers  394 

volume  register  395 

wavL"Iiirm  register  397-;)&3 
tiiretl  pagf    14.  106 

and  ProDOS  16  44 
direel  page  addressing  minlp  35 
direel  page  ^nde^ci^d  jid'dresiiiig 

made  35-;3i6 
direct  page  repiinter  21 
dirfcturies  330 
diret't!>ry  t'ntrx  365 
Uisablebltem  2^1 


index  aSa 


D  i  sable  M  Item  2dO-BSI 
dhMin^  items  2W 
disk  drisfs    aSO.  513  ff. 

3  '/i  inch  6 

5  V,  inch  6 
disk  n|3f  ratine  system    3:29  Jj". 
ditk-drh'p  pfxrt  6 
di^|)br  inodi's  9 
DisposfAll 

Disptisf  Handle    111,  116,  1|S 
UisiKiseMi'iiii  254 
disposing  orblocL-;  111 
DlgCopy  2H7 
DlgCtit  M7 
Dig  Delete  287 
DiMFastf  2S7 

DOt    see  Disitiii  Oscillator  Cliip 
DOC  RAM    41  Kl 

reading    S9 1-392 

iVTih'np  3&1-392 
DOS  :5.3  11 

di)uhic-(jlit  ^  opcrali™  139 
drug  (}ptTiirioii  fiT 
DranWmdaw  185 
DriiuChar    199.  201 
Di'-wCSlrinj;  iWJ-2W 
draviiny!  ISS 
I>r(ivv.MtiiiiBiir    24y.  254 
DrawStriTiK  lS«-2ffll 
DrawTfKt    l!i9-2tHl,  2(19 
dhvers.  RAM-h^tse^l  43^1 
DS  dirK-tiv*-  46 

E.\    JIT  cfltictive  uddreis 

i-ditidilc  U-Ki  iTcm  277-27S 

fdiriiifi  twhiiiqtifs,  sfiindard    72.  277-27S 

cfft'tti\{'  ;iddr^^s  30 

EMShiirDown  127 

EMStai-tiiii  126-127 

fmiildtiiin  Hat;  19 

emulation  iiiiHlf    1.  13 

direct  p:i^e  14 

sta<:k    15.  21 
EiiahlfDUf-hi  2.H1 
EciaNeMrtL'ui  251 
END  directive  42-43 
Endl'iKJate    ISO,  317 


Ensoiiiq  3S9 
ENTRY  dir(?ftivf  43 
EOF  position    347.  354 
EOH  iiistniftiPii  28 
EyU  directive  43 
c-ranf  operation  203 
RniscATL-  204 
ErascOval  204 
Erase  Ptdy  204 
EraSfHecl  204 
Erase  Rgn  204 
EraspBRect  204 
errur  repiirlinK.  foi"  TunL-Hdns 
ErrWriteRIiK-k  439 
ErrWntfChiir  439 
ErrWriteCstriris  43S 
ErrW'rilcLiiiE-  439 
Err  WriieSt  ring  439 
event  handling  l3Bjff 
event  loo|i    125-12B.  133-135 
Event  MdnagLT    70,  125  ff. 
evejil  messagi'  132 
evfiil  ptistiiig  135-136 
event  TL'tord    [3i:i-132,  189 
e\xnt  types  liS 
EventAvai!  135 
events    70.  125 

afti^ate  125 

nifniL-relaled  254-255 

upilntc  125 
cxdiangc  instruct  tons  i'5 
EXE  filrs  50 
EXEC  files  351 
f^lWnsion  RAM  llMl-109 
^^pansjon  slots  3-4 

l-'FGefneratorStiUus  402-^03 
Fl- Soil  ndDi  me  Status  41)2-403 
FFSouiidStatus  402-403 
FKStartiouiid    401.  407 
FFStopSound  402-403 
file  altrihute^;  343-344 
file  IfvH  350-351 
SEe  .system  ID  :345-346 
file  t>pe  codes  .33^f-340 

sTJiiiniiin,-  503/^ 
tileiiame  331 


526  Index 


fill  opLTiition  203 
FillATf  2(1,5 
FillOviil  2(15 
FillFoIy  107 
FillRfcrt  2U5-2yti 
FillBEii  iO^ 
FillHHLXt  2ns 
filtur  pniccdurt" 
alerts  2m 

SFCe-tFik-  364-3f)fi 
Fiii<!nii*-n.  2HI 
FindHtimlk  139 
FiiidWindow 

liiLatiiiii  codes  Ifl4-185 
firmwarr-  RAM  104 
FixAppleML^nu  .113.  317 

FwMeniiBar    S48-249,  254 
Float inf!- Point  Nuinirks  (SANn>  Tl 
Dow-of-ti)iitml  in  Sinn.' til  HIS  2a-2.fi 
FLUSH  3.54 
FiuiliEveLits  135 
tlushine  filfs  3i54 
FMStartup  i9.')-'194 
font  73 

artributfs  ia'i-l^>9 

firiiily  iiii.rnlsfr  1B4 

jitnportional     ]  97 

piirjif  status  IWi' 

seal  in !!  19S 

fiint  charattfh sties  19,3-194 

Font  MiiniiKrr    73,  193-194 

font  rcttiiiiiilf  19fi-197 

r«in[JD  194 

FORMAT  355 

lornnattinj!  disks  355 

FPT    see  Finction  iHniiitcr  table 

frame  opcrHlkm  203 
FramcArc  204 
FramnOvai  204 
FrameFoU    2CJ4,  £07 
Frami-H<-ct  204-20.'5 
FramfRpiL  IM 
Frami-BReLt  2<H 


free  space  (inifhiius  121 

fri-o-fiiriii  syiithcsker  401-403 

Irt'f-nii'b  iiiodf  Syfi 

F'rceMcin  121 

fri'<|iiLniL'V  rcRiMcr,  DOC  3!JS 

F^^|^l^^'ill^lrtw  1^3 

(nil  nattve  m-ide,  dcfiiiitiun  iif  19 

fiiiii.-tit>ii  jMiiiilfr  l:it>lf=  fil 

furiL'tioiis  3 

cffor  Cixina  ^3 

i  E  tiiniinfi  d  result  H2-H3 

t<i(il  set  m 

lyiiii-       port  fi 

C.CB    sef  {{CiiCfatiK  wmtrnl  l>i(>tk 

CRN  dirnrtiw  48 

GL-iifi-dl  '-^I'it  <s».iind}  3S9-390 

Reiieriitor    ICI.  392,  397,  399 

doallotatiiiR  414 

lidtiiii;;  402 

pnnnty  40H-4D9 

staUis  ■m 
Beiierattir  control  bkitV  ^103 
KcTfCTiitor  Ijhif  406 
GEgU  direclivf  43 
CilHjtkCiiloi  iil)U202 
t;flBat:kPat  itiH-im 
GertriirptTliTif'  143 
GctCursorAdr  143 
GflDlilTitiH'  139 
GftD.-rBiittim  281 
GetDltfmBoJi  2N1 
(JotDltcmType  2SI 
CctDltt-niViilui-    ibl.  -Zfi^i 
C;ettirrGU5hjls  437 
(JctError  Device  43H 
Ck-!Fonlliiro    190,  197~iaH 
CriFciri'Ci.lDr  201 
Gcmflndlf'Siy:e  119-120 
GiMliiGltjbals  437 
GpHnpiitDt'Vicrt'  43IS 
GetlKQtniililf  442 
GcllTf\t    2W1-2S2.  285 
GrtMllaiidlf  253 
Ct^tMllt-mMark  252 
GetMItemStyl*?  253 


index 


GetMuusp  141 
GclSevvDltem    271,  280.  2HS 
CftNewModalDialog    269-271,  280.  283 
CctKextEvent    IH'l,  1S9,  2S6-2K7 
CetNtiit Event    12B.  I2S-133,  135-136, 

13K  140 
C  !-tOu  t  Clo  bajs  437-13^! 

GetPeii  19(1 
CctFL-nMask  IHfi 
fiftPenPat  ISS 
CetPtTiSwf  191 
CetPcp-State  190-191 

CelPoilHt'L-t  171 

GctSdUndVuluine  400-401 

CetTal)IeAddrL-_«  403-407 

CftTfxtFace  199 

CftTtKtMi>dc  202 

CET^ROOT_VOL 

CET_DE\_NUM  336-:i,57 

GET.EOF  351-353 

CET_FILE_INFO  .^344 

CE'r_MST^DEV  .157 

CET_LEVEL  :J51 

CET.MARK  353-3.'54 

GET_\AME  3,^7-3^ 

GET_PUEFL\    ^7,  358 

CFT_\1;RSI0N  35^-.3f59 

P:Mjh\  ci5tir(|iniilc  syslfrm    132,  J71-I72 

tiJoba]  Lhc-I^  43 

GJol>iilTi>I,o<:aI    172,  189 

CrafPf)rt  170-171 

graphics  i]ispk>  iru-niorv"  1Q5 

grow  h.js    ley.  176 

CmwVV'ijidow    177.  IBS 

handle    75,  110 

flfrereit'iiLiiii;    1 1^1  ].5 
HiimltoHaitd  120-121 
HandtoPhr  120-121 
lu-adphc?ne  jack    .5.  10 
Uvrtz.  3^2 

He\21iil  499 
Hc-K2Ung  499 


HicJeCurtiiir  143 
HidoDftfm  281 
Hidi^^Window    IRO.  182,  185 
IfTlitt-Mtiui    255-256,  287 
HLotlf    112,  115.  U8-119 
HLiMrkAll  119 

human  iiUcrfiite  miidclines    67-68.  241, 
254 

HUiiLtxt    112.  115,  llS-119 
HUiilxitkAll  119 

I/O  de^Hce 

initiaWHim  439-439 
iiL|iu|  440 

luSital  t>  pcs  4^5-436 

output  439-440 
icon  definlUiJo  279 
iran  items  279 

ID  iiiinihcr.'i,  hr  menu  244-245 

ir>t;n?  44.  u^-i-iie 

I  magf  Writer  11  437 

MoiiseText  ic-ims  437 
iiiitnwHati?  ^ldd^e^il^s  mtjde  32-33 
iinplifMi  addri-ssiii^  made  30 
iii[TfiiieniiTi.a 

index  register  select  flag  19 
index  rcgisk-rs  20 
lndir{?ct  dddr<'ssinp  nmde  36-37 
inforniatioiii  bar    16fi.  175,  17S-179 
liiitCdiuiTable  Uifi 
InitCiirsor    141,  143 
InitTLxtDfv    438-439,  449 
InserlMcnii    243.  24S.  254 
InNiTtMllcin  251 
In!?ta]ICD.A  313 
Install  Fuji  I  196 
INSTIME  dirertivp  4S 
in^tnit'tioii  fifid  41 
instriiL-tiiins.  65816  22 
instnimfnt,  miisii.-y|  409—410 
Inl2Dec  499 
In(2Hex  49S 
iateger  75 

liileger  Math  hiol  set    71,  4Q7  ff. 
ijitcr-resfister  transfpr  inslmrtionji  24 
iTiK'HTUEil  hardlitip  38(1 
and  Sfhcduk^r  71 
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interrupt  mstruotion!;  3() 
inteFrupts    ^7  ff 

IRQ  diiiibic  flag  IS 

software  3S 
liitSuiirte  -142 
InvulRet-t  14U 
InvnIRgii  140 
inverse  display  143 

InvertArc  205 
IiivcrtOval  205 
InvfrtPiily  205 

IiivcrtKiin  203 
IiiVfrtRKtret  205 
IRQ  disable  ^a\i    IS.  3.S 
IRQ  inreirupt&    ^T-.ia.  360 

vector  as 

IsDialonEvent  'ibV^ih" 
item  dL-scriptor  272-273 

Item-dtifiniliiin  [innedurt-  £79-aH0 
itffm* 

adding  lo  diiiloj^s  280-281 
chmgina  attribiitci  281~2fl2. 

j\inp  instructions  26 

K  register  21 
KEEP  directive  42 
key-down  event    129,  140 
keyboartL  7 

keyboard  equivalent    241.  247,  253 
keyboard  events  129 
keyboard  VQ  4:i5 
keyboard  input  441—442 
keyboard  interrupts  442 
KiilPoly  207 

label  Held  41 
labelii 

local  and  global  43 

naming  mles  41 
language  L-ard  104 
LESIiutdown  2fi9 
LESlartup  i69 


Line  203 
line  driiwinji  203 
Linctldil  tool  set    72,  269 
LineTo  20i 

and  pulvRim^  207 
LINKED  lajiguage  50 
Lisa  fi7 

LIST  dir*^-liVf  47 
List  Manager    73.  194 
lisEinp  directives    47 — IS 
load  file  (FniDOS  161  50 
Ifjadi'stor!?  instructions  22-23 
LoadOiicTool    7fi,  H5 
LoadSysFont  195 
LoadTiMils    77-7S,  SO,  85 
loral  coordiiiateji    141.  171-172 
Kk'^I  labials  43 
LocalToClubal  172 
loL-kins  blix-ks    115,  118 
louiicul  ir^lmt'injn^  28 
long  integer  "5 
Iniig  static  te^it  items  276-277 
Lon^aOftc  500 
Ijm^2Hes  49S 
LONCA  directive  44 
LONCI  directive  44 
LSP  instniction  29 

m  flag  19 

MACCEN'  program    49,  75 
Madntosb  XL  67 
macro  definitions    48—49.  68 
macro  files 

APVV  7fi 

tool  sets  495 
magiwines  521 
main  memory  2 
mark  position    (^7,  352,  354 
master  pointer  110 

removal  118 
MaxBWk  121 
Mf:0PY  directive    42.  49 
measuring  te\t  201 
memory  bank.  deRnition  14 
meni'Ory'  expansion  102 
memory  expansion  cards    109,  ^1  ff. 
memory  espansioti;  slot  3 
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Mt-morj'  Managfr    fifi,  102,  HOff. 

av^l^hl^  memnry  1(16 
racraort'  map  102-103 
ine-mfln.  space  10] 
meiiitiry  usage  2 

mcmarv'/iifc-umtilator  atltet  fl^n  19 
meiMi  241 

ralor  256 

creating  343 

menu  bar  241 

creating  248 

size  249 
nit^nu  item 

appcaraiiL'L-  246 

chatigine  attributes  249 

cliangini:  name  249-250 

flietkin.^  251-232 

Close  itf  m  244 

colt)  r-re place  highlighliTijt!:  S47 

deleting  251 

desk  act-oisovf'  itrm  244 

disabhna    246,  250-251 

diviilinj?  line  2-17 

fditiiiij;  244 

ciiablinK  250-251 

iiistrtinn  2,51 

marking    24S.  2f51-2.52. 

text  styk'  2.^2-2.>'J 
Menu  Manager    72.  241 
me-nti  tit  It 

(h^m^iim  mnip  24fl 

hiKhliglilini!  255-2.'5fi 
meiiti/itHni  line  list  243-24-3 
MeniiKey  255 
MeniiSelett  254-255 
MeriuShutiliiwn  243 
MeiiuStiirtup  242 
MIDI    409.  413 
inini-ass4.'iiil]|er  2 
Miscellaneous  Too]  S.-l    70,  144 

MMStartup     115-117.  126 
modal  dialiig  boxes  269-271 
Motiainiiilcji!    270.  2H3-2A5,  ■2HH-2m 
ijindfless  dialog  I xixtK    2fiy,  lH5ff. 
mudificRlioii  ticnt^  344 


modifier  flags  132-1^3 
modifier  keys  123 
inost-^ijInififBnt  bit  IH 
mouse  fi 

mouse  jicttvity,  tii  windows  1H3  ff. 
mouse  fvents  128 

mouse-down    12S,  13S 

m«use-up  12fi, 
Mou5cText    443,  445 
Move    IBS.  100.  199-200 
MoveTo    189,  190,  198-200 
MTShutDoHTi  144 
MTStartup  144 
MVN  instruction    25,  34 
MVF  mstruttiun    25.  24 


native  modt^    J,  13,  44 

ni-gativf  flag  19 

nffjKtive  numbers  19 

New  Desk  AcLt-ssnries    70,  311  jj. 

iiistdllafricin  317 
New-Video  refCister  162 
Nf  wBarColor  25G 
NewUItt-m    271,  2W-281,  2a6 
NewUamlle    110-111.  114.  1I6-11S,  127 
NewliivertColor  2.'j(i 
NEWLl.NE  ,349 
newliiif  eliararter  .14^ 
MewMi-n.i    24a,  24fi.  253-25J 
Ni-wModalDialog    269-271.  2m,  2HS 
NewModeles^Di^ikiS  2*5-2^*6 
NL-wOiitt:oliJr  25f> 
N<-w\Vindow    140.  170.  173.  175-170, 

17S-1TO.  I^i2.  2<W-2(>y 
NMI  iriterni]jts    :17.  .19 
NOP  iiistruetioii  30 
Note  Se(|ueiieer  73 
Note  S>iitliesiwr    7.3.  407-4JW1 
NuU'Alert  -IfiH 
NiiU'OIT   407.  412.  414--415 
Nntedii    407.  4C«,  41,5 
NSSliiitDown  414 
NSStartup    40fi,  4ia-^H3,  415 
NTfjC  viden  purl  7 
riunibcr  t-omersi«n    4^7  ff. 
iiumberinj;  systems  44 — 15 
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OBJ  fiW  42 
objetf  ctitlf  fbniiiil  50 
ObscureCiirsuT  143 
Off«'lPoly  207 
□iie-sh*i(  imidf  397 
opcode  22 
OPEN  34S 

OpenNDA  314 
OpenPaly  207 
gp^ranil  22 

operiitinK  Jiysttms  10-11 
OR  mask  437-43ft 
ORA  iiiit  ruction  28 
disdllfior  iiiikI^    397,  413 
DScilliUor.  haltifip  393 
overfiow  flag  1^-19 

paRp  region  lfi9 

puiiU  05!t'mtion  203 

PainEArL  204 

PaintOval  204 

PaintPoly    204.  207 

PaintRect    204,  206 

PaintRffln  204 

PaiiitRHett  2(H 

pa\L-[lc    IKi-lM,  Kifi.  170-171 

PiLRiiTiTtrxt    277.  252 

partiiil  piithnanie  332 

Past'iil    1 J 

[ijilhiiiine  '^31 

jwlttm  ]S7-ia9 

biickgrouni:] 

mastk  187 
PC  register  21-22 
Pii A  instnu'tifin  23 
PEl  instruction  23 
pen  ISG 

cliiiractE;riS'tics 
pen  modci  191-193 
peri  iMsition  189-190 
pen  sil<e  191 
pen  stuU-  190-191 

htiw  ti."  fhiirge  191 
FeiiNormal  191 
PER  instruct  ion  23 


pcriphfral  m\[  lt>4-Ii:.5 
plLiiUoiii  slots  3 
picture'  ilfciiia  27y 
pKcli  :i(yi-393 
pitthliesid    4(18,  412 
paint,  defiiiilioii  ol  IS7 
pointer  75 
polvRons  207-208 
PtfpLonp  iiiatrn  76-77 
pitpWcird  iTiit-ro  76-77 
Portlnly  field  17!) 
PortRc-cl  field  171 
ports  -1 

PoslE\ent  135-136 
prL-fiitps    332-333,  346 
PRENT  macro  +40 
Print  Maiiapcr  72 
printer  eommands  449 
printer  I/O  435 
prinlt-r  iiutput    437,  449 
FRINTLN  macro  440 
protpssiir  ijtiitus  regi^te^  16-17 
ProDOS  16    11.  72,  :i2iiff 

boot  disk  .vtTuclure  332 

Miiimands    334  ,  336 

entry  ci>nditions  43—44 

errors  334 

memory  usage    102,  104 
ProDOS  S    11.  329 

memory'  "S^RC  lOl 
ProDOS.  antl  the  clock  8 
^^rclg^alll  bank  r<.•J^ist^■^    21,  35 
program  tounter  21-22 

bank  wrapping  22 
program  couiitcT  relative  addressing 
nidile  33 

propram  counter  rriative  Ions  addressing 

mode 
PtrloHand  120-121 
pull  instnJtlions  24 
jiiill-down  menu  241-242 
purge  level  110-113 

setting  119 
PurgeAU  119 
PiirRsHandlc    113,  119 
purging    113,  117,  118 
push  instruictions  23 
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PushLont!  matTP  76 
PushPtr  mam>  76 
PushVVord  macro  76 

QDAiisShutDiwii  143 

yDAiiJiStiirtiip  143 

QDShulDowa  iB2 

QMtartiip    162.  J72 

QukVtlraw  Aii;(iliary  Tmpl  Set    72,  143 

yiiickDrjw  II    7f),  \(\±ff. 

QUIT    50,  35*1-3<5<J 

Quit  Return  Slack  ,159-360 

K.^^^  disk  330 

hiooting  IVhiii  6-7 

hnw  to  use  6 
RAM  Disk  Too]  Set  71 
HAM  expansion  102 
READ  349-350 
HeadAsciiTinii-  144 
ReadChar  440—441 
reading  files    343,  350 
ReadLine  440-441 
RfadHa^mBlixk  400 
Re-adTimi-Het    M,  144-145 
READ,  BLOCK 

ReallwHandlt^    110-111,  113-114,  118 

rectangle,  definiti  nn  n\  187 

reference  books  51S 

fiefrtsh  Desk  top  173 

register  select  flags  19 

registers  15 

reiiamins  files  342-343 

REP  iiislructioi^    19-20,  44 

rt-ply  rerard    363-364.  367 

lifs«l  func-liiin  79 

Rr^f[  interrupts    37,  39 

RrsloreEliindle    110,  113-114.  IIS 

re-lum  address;  26 

KGB  I'idtrii  port  7 

ROL  iintruction  29 

ROM  disk    7.  110 

ROM  ixpiinsion    102,  110 

ROM  spat^  2 

riHJt  directorv  331) 


ROR  instruction  29 
RTI  instruction  38-39 

S1&  files  50 
Siiinplin}{  rato  395 
SANE  71 

scaiJine  control  byte    163-164,  167 
SCR         scanline  control  byte 
sec    •trc  S.530  sifriiil  coniniunicdtions 

controller 
SchAddTtisk  m\ 
Schfdulcr    71.  361 
Scrap  Maiiiigcr  73 
K'roll  arriJw  li5& 

scroll  hrtrs    I&H,  175^176,  17B.  275-276 

selecting  a  filename  362 

SelectWindow  iai,-isg 

SeETTeM  281-2^i2 

st-mitonc  40S 

SEP  instniction    19-20,  44 

serial  ports    5.  449 

SetAIISCBs  ]67 

SftBackColur    197.  2131 

St-tBattPst    l«3-lf!9,  203 

SelRarColors  2.56 

SetCo]orEiilr>  166 

SelCo!i>rTablf  167 

SetCunteiitDraw  ISl 

SptContLTil:Origin  IKl 

SclCurstir    141.  143 

SftDiitflSizf  IRl 

SetDofBiitton  281 

SetDefProL-  l«l 

St-lDItcmBox  281 

SctDJtt'mType  2S1 

SftDlteml'aliii^    2S1.  2S3 

.SetErrCkilKils  437 

SetErr(irD*-vice  43S 

SclFantFIaRS  197 

SflForcColor    197,  201-202 

SetFratm-Color  IHj 

St'tFullBecl  IBI 

SptHaiidlL-Si^t  120 

SctliifoDfdw  Ifil 

ScrtliifoRcfCoti  181 

HetltiClobdls  437 
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Sp  tl  n  pii  t  Dev  ite  438 
SetlTcxt  281-2Sa 
S^-tVIiixGraw  181 
HcrlMfiinTitlc  249 
Si^tMltein    24y.  2.51 
SHMltLiiiMurk  2Ti2 
SptMltfiiiNjime  249-250 
SptMltfiu-SlvIe  2r^2 
SL^OriRiii     171.  177,  ISO.  209 
St-tOutCKibjl!^  437 
SttOiitpul  Di-viw  43fS 

SetPenMask    ISH,  191 
SclPrnM.tdL  191 
St'lPpnPut    m  ISl.  203 
SetPL'iiSiz^  191 
SetPKii  Stale  191 
SftPort  iWi 
SetPur^c    111,  Uy 
S*'tP.ir(!L-Al]  lis 
tittPurUfSlal  196 
Sl-ISCB  167 
SclSLToli  LSI 

Set.SoliJBackPat    ISH-lSy.  203 
St'rSolidP^^nPal    lSS-lb9,  203 
SelSoundVllRgV  402 
SetS-iiindVolunif  400-40] 
SotTcjttFaLe    194.  198 
Si'lTcstMwle  202 
SetTSPlr 

.SetUsLTSoutidlRyx  402 
SelWAP    S4.  127 

SctWTitV  ISI 
SET_t:Or    ^347.  i&^-aSl 
S  F.T  _  F 1 LE  _  I N  FO    34 2-344 
SET.LKVKL  .3^1-351 
SKIDMARK 

5ET_PREFTX    332.  34fi 
SF&;tFilt.-    362^365.  367-:ifi9 
fiFShLitl>(!Wii  3f)2 
SFStai-tiip  362 
shallow  register  IWi 
shadawing    1  (>fi- 1  Vfii 
shape  druwiniT  203 


iii^tfiiititiiis  29 
Sliowf  Cursor  143 
ShowDltfiTi  lh\ 

ShdwWiiiduw    140.  173.  175.  IHO.  Lh2 
filnilDdWii  liiintiiiii  79-M 
SizLAVintluvv  1^5 
Sluts  1.1:1  III  mail  il  5 
soft  switt■he^    3.  104 
sottuiiTf  iiitt'rniiih  40 
SijIidPjtk'n.  lSJi-lfl9 
SONt;  profinuii  414-415 
■luunrl  It) 

output  393 

Liiitpjit  Lliiiiiiielfi  393— ■J^M 
Soiird  OinlrnI  n-^stcr  390-391 
Sound  (iLU  10 
Souiul  Miiriiigcr    7).  399 )J. 
SoimdSlbiitD^iwn  399 
SDundSiyrliip    3^9.  403,  40fi,  408 
Miurct  racU-  fiirniLit  41 

foiiiiiieii^  fii?ld  42 

fomrnt'iit  liiifs  41 

instniL-tiim  fi^-td  41 

bhfl  fifid  41 

ciiKTiiiid  fit^ld  42 
Sr  rcgisU-T    15,  21.  2-3 
speaker    ^,  10,  369.  302 
special  ehaiinltrs  (menu)  244-240 
speed    2.  I'J-IJ.  23 
SHC  files  341 
stafk    14-15,  21.  lOfi 

PmDOS  16  +4 

pigllin^  15 
pushing  15 

stdtk  pfMnter    15,  31,  il 
stack  addressing  niodf  33 
stuck  poiiittT    15,  21.  23 
sis.cV  relativ  e  uddrcssiHK  mode    33-34,  B2. 
stack  rcliitiv  c  indirfcl  indexed  with  Y 

jddressins  iiiodL'  34 
stasie  livles  2S9 

Stiindiird  File  Opwations  Tm>l  Sft  73. 

362 

.STANDABP  ASM  pnigram    79-80,  1S7. 
269,  272 
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START  diretthx-  42-43 

STA  FIT  pro^riim    333-iJ4,  360 

StaitDrawing    177,  ISO.  186 

Startup  fiinctmr  79-SO 

static  text  ittms  276-277 

status  flas^  i(j-IT 

Status  function  TS) 

stitlus  regiiter    ste  professor  status 

register 
SlillDowii  140 
StopAlert  288 

slofige  t>pe  (ProDOS)  341 

STR  niatni  2tH) 
string  priniiiig  440 
SiriiiKWidtli  SOI 
style  word 
subdirettijr>'  330 
siibrniitiiH^s  26 
suhtractioii    20,  27 

effett  of  cam-  flag 

efFfc:  of  devimal  ini>de  flag  IS 
supur  hi-res  graphics  162-167 

colors  9 

geqeral  deseriptiuTi  9 

nieiiior\'  usage  10.5 
swap  mode  397 
switch  L-VfTil  129 
SYMBOL  directive  47 
sync  mode  397 

system  f[>nt    196,  463 

hf'ight  190 
SysttjTi  Loadfr  72 

memnrv'  usage  104 

purge  level    1 13 
Sy&tfm  Monitiir    2,  101. 
system  windfiw  312 
systcm-cuntrol  iiiiitnictiiMis  29-.'3(} 
SystemClick  314 
SystemEdit  3l4 
SystemTask  314 

tahle  Size  397-398 

Ta.«ikMastcT    131.  13&,  l3^i.  ]73,  176-179, 
182-186.  189,  308.  210,  255.  269,  286- 
2a7 


tent  color  201-202 

te\l  di^iplay  memory  105 

lent  items 

reading  value;  281-282 
st-lecting  a  ranUe  2&2 
Test  Tool  Set    71.  435^ 
it-st  traiisih-r  nsixles  202 
TextHt-ad  Block  44fr-441 
TestReader  program,    179.  208-210 
Tt-^tShMlUown  435 
TextSt3rtiip  435 
TextWidth  201 
Text  Write  BicH-k  439-440 
thumb  169 
TickCotmt  L45-146 
ticks    132,  145-146 
lime  formats  144 
TinieToiil-;  84-^5 
tide  bar    168^169.  176 
T[,Moiint\'oliinse  78-79 
TLShutDitwTi  77 

effect  on  RAM-bfised  tools  78 

eflect  on  user  TKf  85 
TLStartup    77.  126 

effect  im  user  TPT  85 
Tijo]  X,otator    SS,  77  ff. 
tiKil  pointier  table  til 
tool  sets  fi7-6S 

L'mirs  74 

general  ^ie^^.■riptioll  ,3 

how  to  iiAe    73— "S 

in  ROM  3 

loading  thi-m  77-78 

structiirf  79 

^umriiirj    fiS.  495 

user-dell  lied  64-ti5 

writing  youi  own    SO  ff. 
TOOL. SETUP  proenam    332.  495 
TotalMem  121 
TFT    m>  tool  iKiinler  table 
TrackCoAwiiy  ISS 
TrackZ^iom  1.15 
TRR  njstruction  2^-29 
TSB  ir>struiilio[i  28-25 
two's-com  piemen  I  numbers  18-19 
TyppLifl  366-367 
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Undo  237 
UnloadOiicTm.l  78 
unl*K-kiiig  1J& 

update  even  I    125,  1-29.  14^-141 

liser  timtral  items  iTfi 
user  itfm^  279 
L'ilNG  dirt-ctivt-  43 

Wr*itiii  fuiictioii  79 
versiun  Tiiiml.er  (PmDOS  16) 

for  pmtohijps  79 
vibrati)    408.  413 
video  biiflfer  162 
video  I/O  435 
vidf  o  t>iitput  443 
^■idleo  RAM  105 
vDiccs    ICl.  :3&2 

VOLUME  U'roDOS)    -Ws.  355-356 
volume  (PmOOSi  330 

c-liaracteFi  sties 

direL-tor^'  .33(I-1'J1 
i'olum*^  (uudiif)  400—401 

t■^>lltTC^I  3*10-391 

WaitCiirHir  143 

WaitMouseUp  140 

WAPT    aec  Work  Area  FoiiittT  Tidile 

waveform    392-393,  395,  3HT,  40i 

wavi-'form  ri'^^i'lLiliiiJii  liHh 

WDM  iiibli'uttii.in  30 

widMas  197 


Window  Manager    72,  161^. 
xvin>.\<m    IBl.  168  ff- 

rhansin^  pnipcrties  IW) 

creating  173 

miMiSP  activity  in    1S3  Jf. 

record    1 70 

Teiriov.'i[iK  132 

text  scrt-cn  448-449 

tide  177 
WiiidSliutD'tJwii  173 
Wiml  ll^tt  up    11  li 

Work  Arey  PuinlL-r  Tiiblr    6^  79,  S4.  127 

WRITE  351-:JS2 

Writet:]iar  439 

WriteCStriiiR  43^1-440 

WritfLinc  43!Ji-^■^U 

WnteRaiiiHluLk    4(Ht-  4U7 

UrtteStriuft  43^-140 

WRITE,  BLOCK  356 

wriliny!  filts  3i^l-^3ni 

X  ting  19-20 

X  ri^gister  £0 

XBA  mstnjt  tion    20.  25 

XCE  instriRlitin    19.  15 

Y  rcfjister  20 

zero  fl^K  Ifj 

zocjfTi  Ijox    ley.  175.  177.  185 
Zixim  Window  185 
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Program  Disk  for 

Exploring  the  Apple  IlGS 
by  Gary  B.  Little 


All  of  the  programs  listed  in  this  book  are  available  on  disk,  in  source  code  form, 
directly  from  the  author.  The  disk  also  contains  several  other  programs,  including  some 
useful  desk  accessories  and  a  program  to  display  and  pri^it  screen  image  files. 

TO  ORDER  the  disk,  simply  clip  or  photocopy  this  entire  page  and  complete  the 
coupon  below.  Enclose  a  check  or  money  order  for  $20.00  in  U.S.  furds.  (California 
residents  add  applicable  state  sales  tax.) 


MAIL  TO:  GARY  LITTLE 

1925  Bayview  Avenue 
Belmont,  CA  94002 


Please  send  me: 

 (quantily)  Disks  to  accompany  Exploring  the  Apple  IlGS,  by  Gary  E.  Little,  at 

$20.00  each. 

 Check  enclosed. 


YOUR  SIGNATURE:  ^  

Name:   Title:  

Company  (if  applicable):  

Addrffi!s: ,  

City:    State:   Zip: 


GARY  B.  UTILE 


A  Addison-Wesley  Publishing  Company 


EXPLORING 
THE  APPLE  liGS 

Best-setltng  author  Gary  B.  Little  reveals  the 
power  of  the  amazing  new  Appfe  lies 

The  Apple  lics  fs  the  sophisticated  new  member  of  the  Apple'  II  family  of 
computers  with  outstanding  color  graphics  and  sound  capabilities.  It  features 
a  powerful  16-bit,  65816  miaoprocessor,  custom  sound  and  graphics  chips,  an 
enhanced  operating  system  called  ProDOS"  16,  and  a  Macintosh  -like  Toolbox 
of  programming  tools  to  help  programmers  easily  create  windows,  pull-down 
menus,  dialog  boxes,  and  other  user  interface  components. 

Now  Gary  B,  Little,  the  author  of  the  acdaimed  Inside  the  Apple  He  and  Inside 
the  Apple  Nc  has  written  an  in-depth,  technical  introduction  to  the  inner  work- 
ings of  the  Apple  Mqs.  Written  for  all  assembly  language  and  Applesoft  BASIC  pro- 
grammers. Ex  ploring  the  Apple  lies  is  a  detailed  study  of  how  the  Apple  IIgs  is 
built  and  how  it  works. 

Little  provides  thorough  discussions  of; 

•  the  architecture  and  capabilities  of  the  65816  microprocessor 

■  software  development  environments  and  utilities 

•  the  Apple  IIgs  Programmer's  Workshop 

•  file  management  with  ProDOS  16 

■  memory  map  and  memory  management 

•  using  Super  Hi-Res  graphics 

•  event  handling 

•  using  the  Apple  IIgs  Toolbox 

Littje's  easy-to-read  style  makes  the  intricacies  of  programming  the  Apple  IIgs 
readily  accessible.  He  analyzes  a  II  the  major  functions  a  prog  rammer  will  have  to 
know  and  shows  how  to  assemble  them  into  a  complete  application.  Each  chapter 
features  extensive  examples  of  program  code.  Exploring  the  Apple  lies  fs  the 
ideaf  guide  to  learning  to  program  Jthe  exciting  Apple  IIgs. 

Gary  B.  Little  is  a  well-known  author,  columnist,  and  software  developer.  He  is  a 
leading  authority  on  the  Apple  II  family  of  computers,  His  books  indude  the  best- 
selling  Inside  the  Apple  lie,  Inside  the  Apple  He,  and  Apple  ProDOS:  Advanced 
Features  for  Programmers.  Gary  is  the  developer  of  the  Point-to- Point  commu- 
nications program  and  he  is  also  a  Contributing  Editor  for  A  +  Magazine.  He  prac- 
tices computer  law  in  Vancouver.  British  Columbia. 
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